API

METHODS

 
 

API Reference

The Stripe API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your secret API key in any public website's client-side code). JSON will be returned in all responses from the API, including errors (though if you're using API bindings, we will convert the response to the appropriate language-specific object).

To make the Stripe API as explorable as possible, accounts have test-mode API keys as well as live-mode API keys. These keys can be active at the same time. Data created with test-mode credentials will never hit the credit card networks and will never cost anyone money.

Libraries

Libraries are available in several languages.

API Endpoint

https://api.stripe.com/
Summary of Resource URL Patterns
  • /v1/charges
  • /v1/charges/{CHARGE_ID}
  • /v1/coupons
  • /v1/coupons/{COUPON_ID}
  • /v1/customers
  • /v1/customers/{CUSTOMER_ID}
  • /v1/customers/{CUSTOMER_ID}/subscription
  • /v1/invoices
  • /v1/invoices/{INVOICE_ID}
  • /v1/invoices/{INVOICE_ID}/lines
  • /v1/invoiceitems
  • /v1/invoiceitems/{INVOICEITEM_ID}
  • /v1/plans
  • /v1/plans/{PLAN_ID}
  • /v1/tokens
  • /v1/tokens/{TOKEN_ID}
  • /v1/events
  • /v1/events/{EVENT_ID}
 

Authentication

You authenticate to the Stripe API by providing one of your API keys in the request. You can manage your API keys from your account. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!

Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

To use your API key, you need only set Stripe.api_key equal to the key. The Ruby library will automatically send this key in each request.

To use your API key, you need only set stripe.api_key equal to the key. The Python library will automatically send this key in each request.

To use your API key, you need only call Stripe::setApiKey() with your key. The PHP library will automatically send this key in each request.

To use your API key, you need only set Stripe.apiKey equal to your key. The Java library will automatically send this key in each request.

To use your API key, you need only call stripe.setApiKey() with your key. The Node.js library will automatically send this key in each request.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

curl https://api.stripe.com/v1/charges \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" );

curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password). You can set a default key, or you can always pass a key directly to an object's constructor. Authentication is transparently handled for you in subsequent method calls. You can set a key by passing it to the Stripe module (a constructor). Authentication is transparently handled for you in subsequent method calls.

A sample test API key has been provided in all the examples on the page, so you can test out any example right away.

 

Errors

Stripe uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Stripe's servers.

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g. a card is declined), we return a 402 error code.

Attributes
type
The type of error returned. Can be invalid_request_error, api_error, or card_error.
message
A human-readable message giving more details about the error. For card errors, these messages can be shown to your users.
code
optional For card errors, a short string from amongst those listed on the right describing the kind of card error that occurred.
param
optional The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.

HTTP Status Code Summary

  • 200 OK - Everything worked as expected.
  • 400 Bad Request - Often missing a required parameter.
  • 401 Unauthorized - No valid API key provided.
  • 402 Request Failed - Parameters were valid but request failed.
  • 404 Not Found - The requested item doesn't exist.
  • 500, 502, 503, 504 Server errors - something went wrong on Stripe's end.

Errors

Types
invalid_request_error Invalid request errors arise when your request has invalid parameters.
api_error API errors cover any other type of problem (e.g. a temporary problem with Stripe's servers) and should turn up only very infrequently.
card_error Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason.
Codes
incorrect_number The card number is incorrect.
invalid_number The card number is not a valid credit card number.
invalid_expiry_month The card's expiration month is invalid.
invalid_expiry_year The card's expiration year is invalid.
invalid_cvc The card's security code is invalid.
expired_card The card has expired.
incorrect_cvc The card's security code is incorrect.
incorrect_zip The card's zip code failed validation.
card_declined The card was declined.
missing There is no card on a customer that is being charged.
processing_error An error occurred while processing the card.
rate_limit An error occurred due to requests hitting the API too quickly. Please email support@stripe.com if you're consistently running into this error.

CVC validation and zip validation can be enabled/disabled in your settings.

Handling errors

Our API bindings can raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability. We recommend always trying to gracefully handle exceptions from our API.

Our API bindings can produce errors for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability.

begin # Use Stripe's bindings... rescue Stripe::CardError => e # Since it's a decline, Stripe::CardError will be caught body = e.json_body err = body[:error] puts "Status is: #{e.http_status}" puts "Type is: #{err[:type]}" puts "Code is: #{err[:code]}" # param is '' in this case puts "Param is: #{err[:param]}" puts "Message is: #{err[:message]}" rescue Stripe::InvalidRequestError => e # Invalid parameters were supplied to Stripe's API rescue Stripe::AuthenticationError => e # Authentication with Stripe's API failed # (maybe you changed API keys recently) rescue Stripe::APIConnectionError => e # Network communication with Stripe failed rescue Stripe::StripeError => e # Display a very generic error to the user, and maybe send # yourself an email rescue => e # Something else happened, completely unrelated to Stripe endtry: # Use Stripe's bindings... pass except stripe.error.CardError, e: # Since it's a decline, stripe.error.CardError will be caught body = e.json_body err = body['error'] print "Status is: %s" % e.http_status print "Type is: %s" % err['type'] print "Code is: %s" % err['code'] # param is '' in this case print "Param is: %s" % err['param'] print "Message is: %s" % err['message'] except stripe.error.InvalidRequestError, e: # Invalid parameters were supplied to Stripe's API pass except stripe.error.AuthenticationError, e: # Authentication with Stripe's API failed # (maybe you changed API keys recently) pass except stripe.error.APIConnectionError, e: # Network communication with Stripe failed pass except stripe.error.StripeError, e: # Display a very generic error to the user, and maybe send # yourself an email pass except Exception, e: # Something else happened, completely unrelated to Stripe passtry { // Use Stripe's bindings... } catch(Stripe_CardError $e) { // Since it's a decline, Stripe_CardError will be caught $body = $e->getJsonBody(); $err = $body['error']; print('Status is:' . $e->getHttpStatus() . "\n"); print('Type is:' . $err['type'] . "\n"); print('Code is:' . $err['code'] . "\n"); // param is '' in this case print('Param is:' . $err['param'] . "\n"); print('Message is:' . $err['message'] . "\n"); } catch (Stripe_InvalidRequestError $e) { // Invalid parameters were supplied to Stripe's API } catch (Stripe_AuthenticationError $e) { // Authentication with Stripe's API failed // (maybe you changed API keys recently) } catch (Stripe_ApiConnectionError $e) { // Network communication with Stripe failed } catch (Stripe_Error $e) { // Display a very generic error to the user, and maybe send // yourself an email } catch (Exception $e) { // Something else happened, completely unrelated to Stripe }try { // Use Stripe's bindings... } catch (CardException e) { // Since it's a decline, CardException will be caught System.out.println("Status is: " + e.getCode()); System.out.println("Message is: " + e.getParam()); } catch (InvalidRequestException e) { // Invalid parameters were supplied to Stripe's API } catch (AuthenticationException e) { // Authentication with Stripe's API failed // (maybe you changed API keys recently) } catch (APIConnectionException e) { // Network communication with Stripe failed } catch (StripeException e) { // Display a very generic error to the user, and maybe send // yourself an email } catch (Exception e) { // Something else happened, completely unrelated to Stripe }// Note: Node.js API does not throw exceptions (except in // the case of missing arguments) // // An error from the Stripe API or an otheriwse asynchronous error // will be available as the first argument of any Stripe method's callback: // E.g. stripe.customers.create({...}, function(err, result) {}); // // Or in the form of a rejected promise. // E.g. stripe.customers.create({...}).then( // function(result) {}, // function(err) {} // ); switch (err.type) { case 'StripeCardError': // A declined card error err.message; // => e.g. "Your card's expiration year is invalid." break; case 'StripeInvalidRequestError': // Invalid parameters were supplied to Stripe's API break; case 'StripeAPIError': // An error occurred internally with Stripe's API break; case 'StripeConnectionError': // Some kind of error occurred during the HTTPS communication break; case 'StripeAuthenticationError': // You probably used an incorrect API key break; }

Pagination

All top-level Stripe API resources have support for bulk fetches — "list" API methods. For instance you can list charges, list customers, and list invoices. These list API methods share a common structure.

Stripe utilizes cursor-based pagination, using the parameter starting_after. Pass starting_after to dictate where in the list you would like to begin (see below).

Pagination Arguments
limit
optional A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
List Response Format
object
string, value is "list"
data
array An array containing the actual response elements, paginated by any request parameters.
has_more
boolean Whether or not there are more elements available after this page. If false, this page is the end of the list.
url
string The URL where this list can be accessed.
curl https://api.stripe.com/v1/customers \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Customer.allimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Customer.all()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Customer::all();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer.all(new HashMap<String, Object>());var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.list(function(err, customers) { // asynchronously called }); { "object": "list", "url": "v1/customers", "has_more": false, "data": [ { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }, {...}, {...} ] } #<Stripe::ListObject:0x3fe634d74498> JSON: { "object": "list", "count": 3, "url": "v1/customers", "data": [ #<Stripe::Customer id=cus_3tHwg1YkHpeHOJ 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }, #<Stripe::Customer[...] ...>, #<Stripe::Customer[...] ...> ] } { object: "list", url: "v1/customers", has_more: false, data: [ <Customer customer id=cus_3tHwg1YkHpeHOJ at 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }, <stripe.Customer[...] ...>, <stripe.Customer[...] ...> ] } Array( "object" => "list", "url" => "v1/customers", "has_more" => false, "data" => Array( [0] => { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" } [1] => <Stripe_Customer[...] ...> [2] => <Stripe_Customer[...] ...> ) ) #<com.stripe.model.CustomerCollection id=#> JSON: { "data": [ com.stripe.model.Customer JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }, #<com.stripe.model.Customer[...] ...>, #<com.stripe.model.Customer[...] ...> ], "has_more": false } { "object": "list", "url": "v1/customers", "has_more": false, "data": [ { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }, {...}, {...} ] }
 

Versioning

When we make backwards-incompatible changes to the API, we release new dated versions. The current version is 2014-03-28. View a changelog and read more about API versions or visit your dashboard to upgrade your API version.

curl https://api.stripe.com/v1/charges \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -H Stripe-Version: 2014-03-28require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe.api_version = "2014-03-28"import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.api_version = '2014-03-28'require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe::setApiVersion("2014-03-28");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Stripe.apiVersion = "2014-03-28";var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.setApiVersion('2014-03-28');
 

Expanding Objects

Many objects contain the id of another object in their response properties. Those objects can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation.

This parameter is available on all API requests, and applies to the response of that request only. You can nest expand requests with the dot property. For example, requesting invoice.customer on a charge will expand the invoice property into a full invoice object, and will then expand the customer property on that invoice into a full customer object. You can expand multiple things at once by sending an array.

curl https://api.stripe.com/v1/charges/ch_103tJZ2eZvKYlo2CSyNNLbLP \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d "expand[]=customer"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Charge.retrieve(:id => "ch_103tJZ2eZvKYlo2CSyNNLbLP", :expand => ['customer'])import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP", expand=['customer'])require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Charge::retrieve(array("id" => "ch_103tJZ2eZvKYlo2CSyNNLbLP", "expand" => array("customer")));The Stripe Java library does not support this feature.var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.charges.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP", { expand: ["customer"] });
 

Metadata

Most Stripe objects (charges, customers, plans, coupons, invoices, invoice items, transfers, and recipients) support user-specified description and metadata parameters.

You can use the description parameter to annotate a charge, for example, with a human-readable description, such as "2 shirts for test@example.com".

In addition to annotating objects with strings, you can use the metadata property to attach key-value data. This is useful to store additional structured information about an object. For example, you could store the email address on a customer to make searching easy, but also annotate it with the UID in case the stored email ever changes.

The description and metadata you specify is returned in API responses.

Note: You can have up to 10 keys today, but we're very curious to hear about any cases where you'd like to use more than that – please email support@stripe.com.

Sample metadata use cases
Link IDs
Attach your system's unique IDs to a Stripe object for easy lookups. Add an order number to a charge, your user ID to a customer or recipient, or a unique receipt number to a transfer, for example.
Shipping information
Store shipping status and tracking numbers on a charge to easily track the status of an order.
Product plan
Annotate a customer, charge, recipient, or transfer with the product in use. For example, a charge may have been made under an 'enterprise' or 'personal' product.
curl https://api.stripe.com/v1/charges \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d amount=400 \ -d currency=usd \ -d card=tok_103t882eZvKYlo2C8g42fbao \ -d "metadata[order_id]=6735"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Charge.create( :amount => 400, :currency => "usd", :card => "tok_103t882eZvKYlo2C8g42fbao", # obtained with Stripe.js, :metadata => {'order_id' => '6735'} )import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Charge.create( amount=400, currency="usd", card="tok_103t882eZvKYlo2C8g42fbao", # obtained with Stripe.js metadata={'order_id': '6735'} )require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Charge::create(array( "amount" => 400, "currency" => "usd", "card" => "tok_103t882eZvKYlo2C8g42fbao", // obtained with Stripe.js, "metadata" => array("order_id" => "6735") ));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> chargeParams = new HashMap<String, Object>(); chargeParams.put("amount", 400); chargeParams.put("currency", "usd"); chargeParams.put("card", "tok_103t882eZvKYlo2C8g42fbao"); // obtained with Stripe.js chargeParams.put("description", "Charge for test@example.com"); chargeParams.put("metadata", initialMetadata); Map<String, String> initialMetadata = new HashMap<String, String>(); initialMetadata.put("order_id", "6735"); chargeParams.put("metadata", initialMetadata); Charge.create(chargeParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.charges.create({ amount: 400, currency: "usd", card: "tok_103t882eZvKYlo2C8g42fbao", // obtained with Stripe.js metadata: {'order_id': '6735'} }); { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { "order_id": "6735" }, "statement_description": null }#<Stripe::Charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { "order_id": "6735" }, "statement_description": null }<Charge charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP at 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { "order_id": "6735" }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { "order_id": "6735" }, "statement_description": null }com.stripe.model.Charge JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { "order_id": "6735" }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { "order_id": "6735" }, "statement_description": null }
 

Charges

To charge a credit or a debit card, you create a new charge object. You can retrieve and refund individual charges as well as list all charges. Charges are identified by a unique random ID.

 

The charge object

Attributes
id
string
object
string, value is "charge"
livemode
boolean
amount
positive integer or zero Amount charged in cents
captured
boolean If the charge was created without capturing, this boolean represents whether or not it is still uncaptured or has since been captured.
card
hash, card object Hash describing the card used to make the charge
created
timestamp
currency
currency Three-letter ISO currency code representing the currency in which the charge was made.
paid
boolean
refunded
boolean Whether or not the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
refunds
hash A list of refunds that have been applied to the charge.
amount_refunded
positive integer or zero Amount in cents refunded (can be less than the amount attribute on the charge if a partial refund was issued)
balance_transaction
customer
description
string
dispute
hash, dispute object Details about the dispute if the charge has been disputed
failure_code
string Error code explaining reason for charge failure if available (see https://stripe.com/docs/api#errors for a list of codes)
failure_message
string Message to user further explaining reason for charge failure if available
invoice
metadata
metadata hash A set of key/value pairs that you can attach to a charge object. It can be useful for storing additional information about the charge in a structured format.
statement_description
string Extra information about a charge for the customer’s credit card statement.
{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }#<Stripe::Charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }<Charge charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP at 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }com.stripe.model.Charge JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }
 

Creating a new charge (charging a credit card)

To charge a credit card, you create a new charge object. If your API key is in test mode, the supplied card won't actually be charged, though everything else will occur as if in live mode. (Stripe assumes that the charge would have completed successfully).

Arguments
amount
required A positive integer in the smallest currency unit (e.g 100 cents to charge $1.00, or 1 to charge ¥1, a 0-decimal currency) representing how much to charge the card. The minimum amount is $0.50 (or equivalent in charge currency).
currency
required 3-letter ISO code for currency.
customer
optional, either customer or card is required The ID of an existing customer that will be charged in this request.
card
optional, either card or customer is required A card to be charged. If you also pass a customer ID, the card must be the ID of a card belonging to the customer. Otherwise, if you do not pass a customer ID, the card you provide must either be a token, like the ones returned by Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobject containing a user's credit card details, with the options described below. Although not all information is required, the extra info helps prevent fraud.
description
optional, default is nullnilNonenullnullnull An arbitrary string which you can attach to a charge object. It is displayed when in the web interface alongside the charge. Note that if you use Stripe to send automatic email receipts to your customers, your receipt emails will include the description of the charge(s) that they are describing.
metadata
optional, default is { } A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format. It's often a good idea to store an email address in metadata for tracking later.
capture
optional, default is true Whether or not to immediately capture the charge. When false, the charge issues an authorization (or pre-authorization), and will need to be captured later. Uncaptured charges expire in 7 days. For more information, see authorizing charges and settling later.
statement_description
optional, default is nullnilNonenullnullnull An arbitrary string to be displayed alongside your company name on your customer's credit card statement. This may be up to 15 characters. As an example, if your website is RunClub and you specify 5K Race Ticket, the user will see
RUNCLUB 5K RACE TICKET. The statement description may not include <>"' characters. While most banks display this information consistently, some may display it incorrectly or not at all.
application_fee
optional A fee in cents that will be applied to the charge and transferred to the application owner's Stripe account. The request must be made with an OAuth key in order to take an application fee. For more information, see the application fees documentation.
Returns

Returns a charge object if the charge succeeded. ReturnsRaisesRaisesThrowsThrowsThrows an error if something goes wrong. A common source of error is an invalid or expired card, or a valid card with insufficient available balance.

If the cvccvccvccvccvccvc parameter is provided, Stripe will attempt to check the CVC's correctness, and the check's result will be returned. Similarly, If address_line1address_line1address_line1address_line1address_line1address_line1 or address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip are provided, Stripe will similarly try to check the validity of those parameters. Some banks do not support checking one or more of these parameters, in which case Stripe will return an 'unchecked' result. Also note that, depending on the bank, charges can succeed even when passed incorrect CVC and address information.

POST https://api.stripe.com/v1/chargesStripe::Charge.createstripe.Charge.create()Stripe_Charge::create();Charge.create();stripe.charges.create(); curl https://api.stripe.com/v1/charges \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d amount=400 \ -d currency=usd \ -d card=tok_103t882eZvKYlo2C8g42fbao \ -d "description=Charge for test@example.com"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Charge.create( :amount => 400, :currency => "usd", :card => "tok_103t882eZvKYlo2C8g42fbao", # obtained with Stripe.js :description => "Charge for test@example.com" )import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Charge.create( amount=400, currency="usd", card="tok_103t882eZvKYlo2C8g42fbao", # obtained with Stripe.js description="Charge for test@example.com" )require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Charge::create(array( "amount" => 400, "currency" => "usd", "card" => "tok_103t882eZvKYlo2C8g42fbao", // obtained with Stripe.js "description" => "Charge for test@example.com" ));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> chargeParams = new HashMap<String, Object>(); chargeParams.put("amount", 400); chargeParams.put("currency", "usd"); chargeParams.put("card", "tok_103t882eZvKYlo2C8g42fbao"); // obtained with Stripe.js chargeParams.put("description", "Charge for test@example.com"); chargeParams.put("metadata", initialMetadata); Charge.create(chargeParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.charges.create({ amount: 400, currency: "usd", card: "tok_103t882eZvKYlo2C8g42fbao", // obtained with Stripe.js description: "Charge for test@example.com" }); { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }#<Stripe::Charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }<Charge charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP at 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }com.stripe.model.Charge JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }

Verification Reponses

CVC Verification - card[cvc_check]
Code Details
pass The CVC provided is correct
fail The CVC provided is incorrect
unchecked The customer's bank did not check the CVC
Address Line - card[address_line1_check]
Code Details
pass The first address line provided is correct
fail The first address line provided is incorrect
unchecked The customer's bank did not check the first address line
Address ZIP - card[address_zip_check]
Code Details
pass The ZIP code provided is correct
fail The ZIP code provided is incorrect
unchecked The customer's bank did not check the ZIP code
 

Retrieving a Charge

Retrieves the details of a charge that has previously been created. Supply the unique charge ID that was returned from your previous request, and Stripe will return the corresponding charge information. The same information is returned when creating or refunding the charge.

Arguments
id
required The identifier of the charge to be retrieved.
Returns

Returns a charge object if a valid identifier was provided, and returnsraisesraisesthrowsthrowsthrows an error otherwise.

GET https://api.stripe.com/v1/charges/{CHARGE_ID}Stripe::Charge.retrieve({CHARGE_ID})stripe.Charge.retrieve({CHARGE_ID})Stripe_Charge::retrieve({CHARGE_ID});Charge.retrieve({CHARGE_ID});stripe.charges.retrieve({CHARGE_ID}); curl https://api.stripe.com/v1/charges/ch_103tJZ2eZvKYlo2CSyNNLbLP \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Charge::retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP");var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.charges.retrieve( "ch_103tJZ2eZvKYlo2CSyNNLbLP", function(err, charge) { // asynchronously called } ); { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }#<Stripe::Charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }<Charge charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP at 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }com.stripe.model.Charge JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }
 

Updating a Charge

Updates the specified charge by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

This request accepts only the description and metadata as arguments.

Arguments
description
optional, default is nullnilNonenullnullnull An arbitrary string which you can attach to a recipient object. It is displayed alongside the recipient in the web interface. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
metadata
optional, default is { }{ }{ }{ }{ }{ } A set of key/value pairs that you can attach to a charge object. It can be useful for storing additional information about the charge in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to nullnilNonenullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnull, then save.
Returns

Returns the charge object if the update succeeded. This call will returnraiseraisethrowthrowthrow an error if update parameters are invalid.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}ch = Stripe::Charge.retrieve({CHARGE_ID}) ch.description = {NEW_DESCRIPTION} ... cu.save ch = stripe.Charge.retrieve({CHARGE_ID}) ch.description = {NEW_DESCRIPTION} ... ch.save() $ch = Stripe_Charge::retrieve({CHARGE_ID}); $ch->description = {NEW_DESCRIPTION}; ... $ch->save(); Charge ch = Charge.retrieve({CHARGE_ID}); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("description", {NEW_DESCRIPTION}); ... ch.update(updateParams);stripe.charges.update({CHARGE_ID}, { description: {NEW_DESCRIPTION} }); curl https://api.stripe.com/v1/charges/ch_103tJZ2eZvKYlo2CSyNNLbLP \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d "description=Charge for test@example.com"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ch = Stripe::Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP") ch.description = "Charge for test@example.com" ch.saveimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ch = stripe.Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP") ch.description = "Charge for test@example.com" ch.save()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $ch = Stripe_Charge::retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP"); $ch->description = "Charge for test@example.com"; $ch->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Charge ch = Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP"); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("description", "Charge for test@example.com"); ch.update(updateParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.charges.update( "ch_103tJZ2eZvKYlo2CSyNNLbLP", { description: "Charge for test@example.com" }, function(err, charge) { // asynchronously called } ); { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": "Charge for test@example.com", "dispute": null, "metadata": { }, "statement_description": null }#<Stripe::Charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": "Charge for test@example.com", "dispute": null, "metadata": { }, "statement_description": null }<Charge charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP at 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": "Charge for test@example.com", "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": "Charge for test@example.com", "dispute": null, "metadata": { }, "statement_description": null }com.stripe.model.Charge JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": "Charge for test@example.com", "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 0, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": "Charge for test@example.com", "dispute": null, "metadata": { }, "statement_description": null }
 

Refunding a Charge

Refunds 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.

You can optionally refund only part of a charge. You can do so as many times as you wish until the entire charge has been refunded.

Once entirely refunded, a charge can't be refunded again. This method will returnraiseraisethrowthrowthrow an error when called on an already-refunded charge, or when trying to refund more money than is left on a charge.

Arguments
id
required The identifier of the charge to be refunded.
amount
optional, default is entire charge A positive integer in cents representing how much of this charge to refund. Can only refund up to the unrefunded amount remaining of the charge.
refund_application_fee
optional Boolean indicating whether the application fee should be refunded when refunding this charge. If a full charge refund is given, the full application fee will be refunded. Else, the application fee will be refunded with an amount proportional to the amount of the charge refunded. An application fee can only be refunded by the application that created the charge.
Returns

Returns the charge object if the refund succeeded. ReturnsRaisesRaisesThrowsThrowsThrows an error if the charge has already been refunded or an invalid charge identifier was provided.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/refundch = Stripe::Charge.retrieve({CHARGE_ID}) ch.refund ch = stripe.Charge.retrieve({CHARGE_ID}) ch.refund() $ch = Stripe_Charge::retrieve({CHARGE_ID}); $ch->refund(); ch = Charge.retrieve({CHARGE_ID}); ch.refund(); stripe.charges.refund({CHARGE_ID}); curl https://api.stripe.com/v1/charges/ch_103tJZ2eZvKYlo2CSyNNLbLP/refund \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X POSTrequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ch = Stripe::Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP") ch.refundimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ch = stripe.Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP") ch.refund()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $ch = Stripe_Charge::retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP"); $ch->refund();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; ch = Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP"); ch.refund();var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.charges.refund( "ch_103tJZ2eZvKYlo2CSyNNLbLP", function(err, charge) { // asynchronously called } ); { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": true, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }#<Stripe::Charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": true, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }<Charge charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP at 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": true, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": true, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }com.stripe.model.Charge JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": true, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": true, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }
 

Capture a charge

Capture the payment of an existing, uncaptured, charge. This is the second half of the two-step payment flow, where first you created a charge with the capture option set to false.

Uncaptured payments expire exactly seven days after they are created. If they are not captured by that point in time, they will be marked as refunded and will no longer be capturable.

Arguments
id
required
amount
optional The amount to capture, which must be less than or equal to the original amount. Any additional amount will be automatically refunded.
application_fee
optional An application fee to add on to this charge. Can only be used with Stripe Connect.
Returns

Returns the charge object, with an updated captured property (set to true). Capturing a charge will always succeed, unless the charge is already refunded, or expired, or an invalid capture amount is specified, in which case this method will returnraiseraisethrowthrowthrow an error.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/capturech = Stripe::Charge.retrieve({CHARGE_ID}) ch.capture ch = stripe.Charge.retrieve({CHARGE_ID}) ch.capture() $ch = Stripe_Charge::retrieve({CHARGE_ID}); $ch->capture(); ch = Charge.retrieve({CHARGE_ID}); ch.capture(); stripe.charges.capture({CHARGE_ID}); curl https://api.stripe.com/v1/charges/ch_103tJZ2eZvKYlo2CSyNNLbLP/capture \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X POSTrequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ch = Stripe::Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP") ch.captureimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ch = stripe.Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP") ch.capture()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $ch = Stripe_Charge::retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP"); $ch->capture();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; ch = Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP"); ch.capture();var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.charges.capture("ch_103tJZ2eZvKYlo2CSyNNLbLP", function(err, charge) { // asynchronously called }); { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }#<Stripe::Charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }<Charge charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP at 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": "True", "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }com.stripe.model.Charge JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": "true", "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": "true", "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }
 

List all Charges

Returns a list of charges you've previously created. The charges are returned in sorted order, with the most recent charges appearing first.

Arguments
created
optional A filter on the list based on the object created field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:
customer
optional Only return charges for the customer specified by this customer ID.
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
Returns

A dictionaryhashdictionaryassociative arrayMapobject with a data property that contains an array of up to limit charges, starting after charge starting_after. Each entry in the array is a separate charge object. If no more charges are available, the resulting array will be empty. If you provide a non-existent customer ID, this call returnsraisesraisesthrowsthrowsthrows an error.

You can optionally request that the response include the total count of all charges that match your filters. To do so, specify `include[]=total_count` in your request.

GET https://api.stripe.com/v1/chargesStripe::Charge.allstripe.Charge.all()Stripe_Charge::all();Charge.all(Map options);stripe.charges.list(); curl https://api.stripe.com/v1/charges?count=3 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Charge.all(:count => 3)import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Charge.all(count=3)require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Charge::all(array("count" => 3));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> chargeParams = new HashMap<String, Object>(); chargeParams.put("count", 3); Charge.all(chargeParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.charges.list({ count: 3 }, function(err, charges) { // asynchronously called }); { "object": "list", "url": "/v1/charges", "has_more": false, "data": [ { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }, {...}, {...} ] } #<Stripe::ListObject:0x3fe634d74498> JSON: { "object": "list", "count": 3, "url": "/v1/charges", "data": [ #<Stripe::Charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }, #<Stripe::Charge[...] ...>, #<Stripe::Charge[...] ...> ] } { object: "list", url: "/v1/charges", has_more: false, data: [ <Charge charge id=ch_103tJZ2eZvKYlo2CSyNNLbLP at 0x00000a> JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }, <stripe.Charge[...] ...>, <stripe.Charge[...] ...> ] } Array( "object" => "list", "url" => "/v1/charges", "has_more" => false, "data" => Array( [0] => { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null } [1] => <Stripe_Charge[...] ...> [2] => <Stripe_Charge[...] ...> ) ) #<com.stripe.model.ChargeCollection id=#> JSON: { "data": [ com.stripe.model.Charge JSON: { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }, #<com.stripe.model.Charge[...] ...>, #<com.stripe.model.Charge[...] ...> ], "has_more": false } { "object": "list", "url": "/v1/charges", "has_more": false, "data": [ { "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": false, "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }, {...}, {...} ] }
 

Customers

Customer objects allow you to perform recurring charges and track multiple charges that are associated with the same customer. The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers.

 

The customer object

Attributes
id
string
object
string, value is "customer"
livemode
boolean
cards
list
created
timestamp
account_balance
integer Current balance, if any, being stored on the customer’s account. If negative, the customer has credit to apply to the next invoice. If positive, the customer has an amount owed that will be added to the next invoice. The balance does not refer to any unpaid invoices; it solely takes into account amounts that have yet to be successfully applied to any invoice. This balance is only taken into account for recurring charges.
currency
string The currency the customer can be charged in for recurring billing purposes (subscriptions, invoices, invoice items).
default_card
delinquent
boolean Whether or not the latest charge for the customer’s latest invoice has failed
description
string
discount
hash, discount object Describes the current discount active on the customer, if there is one.
email
string
metadata
metadata hash A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format.
subscriptions
list The customer’s current subscriptions, if any
{ "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }#<Stripe::Customer id=cus_3tHwg1YkHpeHOJ 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }<Customer customer id=cus_3tHwg1YkHpeHOJ at 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }{ "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }com.stripe.model.Customer JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }{ "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }
 

Creating a New Customer

Creates a new customer object.

Arguments
account_balance
optional An integer amount in cents that is the starting account balance for your customer. A negative amount represents a credit that will be used before attempting any charges to the customer’s card; a positive amount will be added to the next invoice.
card
optional The card can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below). Passing card will create a new card, make it the new customer default card, and delete the old customer default if one exists. If you want to add additional cards instead of replacing the existing default, use the card creation API. Whenever you attach a card to a customer, Stripe will automatically validate the card.
coupon
optional If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the API will not have the discount.
description
optional An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
email
optional Customer’s email address. It’s displayed alongside the customer in your dashboard and can be useful for searching and tracking. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
metadata
optional A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
plan
optional The identifier of the plan to subscribe the customer to. If provided, the returned customer object has a ‘subscription’ attribute describing the state of the customer’s subscription
quantity
optional The quantity you’d like to apply to the subscription you’re creating. For example, if your plan is 10 cents/user/month, and your customer has 5 users, you could pass 5 as the quantity to have the customer charged 50 cents (5 x 10 cents) monthly. Defaults to 1 if not set. Only applies when the plan parameter is also provided.
trial_end
optional UTC integer timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer’s trial immediately. Only applies when the plan parameter is also provided.
Returns

Returns a customer object if the call succeeded. The returned object will have information about subscriptions, discount, and cards, if that information has been provided. If a non-free plan is specified and a card is not provided (unless the plan has a trial period), the call will returnraiseraisethrowthrowthrow an error. If a non-existent plan or a non-existent or expired coupon is provided, the call will returnraiseraisethrowthrowthrow an error.

If a card has been attached to the customer, the returned customer object will have a default_card attribute, which is an ID that can be expanded into the full card details when retrieving the customer.

POST https://api.stripe.com/v1/customersStripe::Customer.createstripe.Customer.create()Stripe_Customer::create();Customer.create();stripe.customers.create(); curl https://api.stripe.com/v1/customers \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d "description=Customer for test@example.com" \ -d card=tok_103t882eZvKYlo2C8g42fbaorequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Customer.create( :description => "Customer for test@example.com", :card => "tok_103t882eZvKYlo2C8g42fbao" # obtained with Stripe.js )import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Customer.create( description="Customer for test@example.com", card="tok_103t882eZvKYlo2C8g42fbao" # obtained with Stripe.js )require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Customer::create(array( "description" => "Customer for test@example.com", "card" => "tok_103t882eZvKYlo2C8g42fbao" // obtained with Stripe.js ));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> customerParams = new HashMap<String, Object>(); customerParams.put("description", "Customer for test@example.com"); customerParams.put("card", "tok_103t882eZvKYlo2C8g42fbao"); // obtained with Stripe.js Customer.create(customerParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.create({ description: 'Customer for test@example.com', card: "tok_103t882eZvKYlo2C8g42fbao" // obtained with Stripe.js }, function(err, customer) { // asynchronously called }); { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }#<Stripe::Customer id=cus_3tHwg1YkHpeHOJ 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }<Customer customer id=cus_3tHwg1YkHpeHOJ at 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }{ "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }com.stripe.model.Customer JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }{ "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }
 

Retrieving a Customer

Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.

Arguments
id
required The identifier of the customer to be retrieved.
Returns

Returns a customer object if a valid identifier was provided. When requesting the ID of a customer that has been deleted, a subset of the customer's information will be returned, including a "deleted" property, which will be true.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}Stripe::Customer.retrieve({CUSTOMER_ID})stripe.Customer.retrieve({CUSTOMER_ID})Stripe_Customer::retrieve({CUSTOMER_ID});Customer.retrieve({CUSTOMER_ID});stripe.customers.retrieve({CUSTOMER_ID}); curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer.retrieve("cus_3tHwg1YkHpeHOJ");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; stripe.customers.retrieve("cus_3tHwg1YkHpeHOJ", function(err, customer) { // asynchronously called }); { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }#<Stripe::Customer id=cus_3tHwg1YkHpeHOJ 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }<Customer customer id=cus_3tHwg1YkHpeHOJ at 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }{ "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }com.stripe.model.Customer JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }{ "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }
 

Updating a Customer

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the card parameter, that becomes the customer's active card to be used for all charges in the future. When you update a customer to a new valid card, the last unpaid invoice (if one exists) will be retried automatically.

This request accepts mostly the same arguments as the customer creation call.

Arguments
account_balance
optional An integer amount in cents that is the starting account balance for your customer. A negative amount represents a credit that will be used before attempting any charges to the customer’s card; a positive amount will be added to the next invoice.
card
optional The card can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below). Passing card will create a new card, make it the new customer default card, and delete the old customer default if one exists. If you want to add additional cards instead of replacing the existing default, use the card creation API. Whenever you attach a card to a customer, Stripe will automatically validate the card.
coupon
optional If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the API will not have the discount.
default_card
optional ID of card to make the customer’s new default for invoice payments
description
optional An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
email
optional Customer’s email address. It’s displayed alongside the customer in your dashboard and can be useful for searching and tracking. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
metadata
optional A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
Returns

Returns the customer object if the update succeeded. ReturnsRaisesRaisesThrowsThrowsThrows an error if update parameters are invalid (e.g. specifying an invalid coupon or an invalid card).

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}cu = Stripe::Customer.retrieve({CUSTOMER_ID}) cu.description = {NEW_DESCRIPTION} ... cu.save cu = stripe.Customer.retrieve({CUSTOMER_ID}) cu.description = {NEW_DESCRIPTION} ... cu.save() $cu = Stripe_Customer::retrieve({CUSTOMER_ID}); $cu->description = {NEW_DESCRIPTION}; ... $cu->save(); Customer cu = Customer.retrieve({CUSTOMER_ID}); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("description", {NEW_DESCRIPTION}); ... cu.update(updateParams);stripe.customers.update({CUSTOMER_ID}, { description: {NEW_DESCRIPTION}, ... }); curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d "description=Customer for test@example.com"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" cu = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") cu.description = "Customer for test@example.com" cu.card = "tok_103t882eZvKYlo2C8g42fbao" # obtained with Stripe.js cu.saveimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" cu = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") cu.description = "Customer for test@example.com" cu.save()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $cu->description = "Customer for test@example.com"; $cu->card = "tok_103t882eZvKYlo2C8g42fbao"; // obtained with Stripe.js $cu->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("description", "Customer for test@example.com"); cu.update(updateParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.update("cus_3tHwg1YkHpeHOJ", { description: "Customer for test@example.com" }, function(err, customer) { // asynchronously called }); { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": "Customer for test@example.com", "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }#<Stripe::Customer id=cus_3tHwg1YkHpeHOJ 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": "Customer for test@example.com", "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }<Customer customer id=cus_3tHwg1YkHpeHOJ at 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": "Customer for test@example.com", "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }{ "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": "Customer for test@example.com", "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }com.stripe.model.Customer JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": "Customer for test@example.com", "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }{ "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": "Customer for test@example.com", "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }
 

Deleting a Customer

Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscription on the customer.

Arguments
id
required The identifier of the customer to be deleted.
Returns

Returns an object with a deleted parameter on success. If the customer ID does not exist, this call returnsraisesraisesthrowsthrowsthrows an error.

Unlike other objects, deleted customers can still be retrieved through the API, in order to be able to track the history of customers while still removing their credit card details and preventing any further operations to be performed (such as adding a new subscription).

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}cu = Stripe::Customer.retrieve({CUSTOMER_ID}) cu.delete cu = stripe.Customer.retrieve({CUSTOMER_ID}) cu.delete() $cu = Stripe_Customer::retrieve({CUSTOMER_ID}); $cu->delete(); Customer cu = Customer.retrieve({CUSTOMER_ID}); cu.delete(); stripe.customers.del({CUSTOMER_ID}); curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X DELETErequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" cu = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") cu.deleteimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" cu = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") cu.delete()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $cu->delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); cu.delete();var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.del( "cus_3tHwg1YkHpeHOJ", function(err, confirmation) { // asynchronously called } ); { "deleted": true, "id": "cus_3tHwg1YkHpeHOJ" }#<Stripe::Object id=cus_3tHwg1YkHpeHOJ 0x00000a> JSON: { "deleted": true, "id": "cus_3tHwg1YkHpeHOJ" }<Object object id=cus_3tHwg1YkHpeHOJ at 0x00000a> JSON: { "deleted": true, "id": "cus_3tHwg1YkHpeHOJ" }{ "deleted": true, "id": "cus_3tHwg1YkHpeHOJ" }com.stripe.model.Object JSON: { "deleted": true, "id": "cus_3tHwg1YkHpeHOJ" }{ "deleted": true, "id": "cus_3tHwg1YkHpeHOJ" }
 

List all Customers

Returns a list of your customers. The customers are returned sorted by creation date, with the most recently created customers appearing first.

Arguments
created
optional A filter on the list based on the object created field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
Returns

A dictionaryhashdictionaryassociative arrayMapobject with a data property that contains an array of up to limit customers, starting after customer starting_after. Each entry in the array is a separate customer object. If no more customers are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrow an error.

You can optionally request that the response include the total count of all customers that match your filters. To do so, specify `include[]=total_count` in your request.

GET https://api.stripe.com/v1/customersStripe::Customer.allstripe.Customer.all()Stripe_Customer::all();Customer.all(Map options);stripe.customers.list(); curl https://api.stripe.com/v1/customers \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Customer.allimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Customer.all()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Customer::all();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer.all(new HashMap<String, Object>());var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.list(function(err, customers) { // asynchronously called }); { "object": "list", "url": "v1/customers", "has_more": false, "data": [ { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }, {...}, {...} ] } #<Stripe::ListObject:0x3fe634d74498> JSON: { "object": "list", "count": 3, "url": "v1/customers", "data": [ #<Stripe::Customer id=cus_3tHwg1YkHpeHOJ 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }, #<Stripe::Customer[...] ...>, #<Stripe::Customer[...] ...> ] } { object: "list", url: "v1/customers", has_more: false, data: [ <Customer customer id=cus_3tHwg1YkHpeHOJ at 0x00000a> JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }, <stripe.Customer[...] ...>, <stripe.Customer[...] ...> ] } Array( "object" => "list", "url" => "v1/customers", "has_more" => false, "data" => Array( [0] => { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" } [1] => <Stripe_Customer[...] ...> [2] => <Stripe_Customer[...] ...> ) ) #<com.stripe.model.CustomerCollection id=#> JSON: { "data": [ com.stripe.model.Customer JSON: { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }, #<com.stripe.model.Customer[...] ...>, #<com.stripe.model.Customer[...] ...> ], "has_more": false } { "object": "list", "url": "v1/customers", "has_more": false, "data": [ { "object": "customer", "created": 1398040345, "id": "cus_3tHwg1YkHpeHOJ", "livemode": false, "description": null, "email": "seller@seller.com", "delinquent": false, "metadata": { "sgUserId": "535465c944aef51e1ef421c2" }, "subscriptions": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions", "data": [ { "id": "sub_3tHwhpzI1u75AY", "plan": { "interval": "month", "name": "Monthly Plan", "created": 1391206393, "amount": 1000, "currency": "usd", "id": "monthly", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398040346, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398040346, "current_period_end": 1400632346, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } ] }, "discount": null, "account_balance": 0, "currency": "usd", "cards": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/customers/cus_3tHwg1YkHpeHOJ/cards", "data": [ { "id": "card_103tHw2eZvKYlo2Cuyg9fepG", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 5, "exp_year": 2015, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": null, "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null } ] }, "default_card": "card_103tHw2eZvKYlo2Cuyg9fepG" }, {...}, {...} ] }
 

Cards

You can store multiple credit cards for a customer in order to charge the customer later.

 

The card object

Attributes
id
string ID of card (used in conjunction with a customer ID)
object
string, value is "card"
exp_month
integer
exp_year
integer
fingerprint
string Uniquely identifies this particular card number. You can use this attribute to check whether two customers who’ve signed up with you are using the same card number, for example.
last4
string
type
string Card brand. Can be Visa, American Express, MasterCard, Discover, JCB, Diners Club, or Unknown.
address_city
string
address_country
string Billing address country, if provided when creating card
address_line1
string
address_line1_check
string If address_line1 was provided, results of the check: pass, fail, or unchecked.
address_line2
string
address_state
string
address_zip
string
address_zip_check
string If address_zip was provided, results of the check: pass, fail, or unchecked.
country
string Two-letter ISO code representing the country of the card. You could use this attribute to get a sense of the international breakdown of cards you’ve collected.
customer
cvc_check
string If a CVC was provided, results of the check: pass, fail, or unchecked
name
string Cardholder name
{ "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }#<Stripe::Card id=card_103tJZ2eZvKYlo2CxOfJvLy0 0x00000a> JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }<Card card id=card_103tJZ2eZvKYlo2CxOfJvLy0 at 0x00000a> JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }{ "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }com.stripe.model.Card JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }{ "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }
 

Creating a new card

When you create a new credit card, you must specify a customer.

Creating a new credit card will not change the customer's existing default credit card; you should update the customer with a new default_card for that. If the customer has no default credit card, the added credit card will become the default.

Arguments
card
required The card can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below). Whenever you create a new card for a customer, Stripe will automatically validate the card.
Returns

Returns the card object.

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/cardscustomer = Stripe::Customer.retrieve({CUSTOMER_ID}) customer.cards.create({:card => TOKEN_ID}) customer = stripe.Customer.retrieve({CUSTOMER_ID}) customer.cards.create(card={TOKEN_ID}) $customer = Stripe_Customer::retrieve({CUSTOMER_ID}); $customer.cards->create(array("card" => {TOKEN_ID})); Customer cu = Customer.retrieve({CUSTOMER_ID}); Map params = new HashMap(); params.put("card", {TOKEN_ID}); cu.cards->create(params); stripe.customers.createCard({CUSTOMER_ID}, { card: {TOKEN_ID} }); curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ/cards \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d card=token_idrequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") customer.cards.create(:card => "tok_103t882eZvKYlo2C8g42fbao")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") customer.cards.create(card="tok_103t882eZvKYlo2C8g42fbao")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $cu->cards->create(array("card" => "tok_103t882eZvKYlo2C8g42fbao"));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); Map<String, Object> params = new HashMap<String, Object>(); params.put("card", "tok_103t882eZvKYlo2C8g42fbao"); cu.createCard(params)var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.createCard( "cus_3tHwg1YkHpeHOJ", {card: "tok_103t882eZvKYlo2C8g42fbao"}, function(err, card) { // asynchronously called } ); { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }#<Stripe::Card id=card_103tJZ2eZvKYlo2CxOfJvLy0 0x00000a> JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }<Card card id=card_103tJZ2eZvKYlo2CxOfJvLy0 at 0x00000a> JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }{ "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }com.stripe.model.Card JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }{ "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }
 

Retrieving a customer's card

By default, you can see the 10 most recent cards stored on a customer directly on the customer object, but you can also retrieve details about a specific card stored on the customer.

Arguments
id
required ID of card to retrieve
customer
required
Returns

Returns the card object.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/cards/{CARD_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID}) card = customer.cards.retrieve({CARD_ID}) customer = stripe.Customer.retrieve({CUSTOMER_ID}) card = customer.cards.retrieve({CARD_ID}) $customer = Stripe_Customer::retrieve({CUSTOMER_ID}); $card = $customer->cards->retrieve({CARD_ID})); Customer cu = Customer.retrieve({CUSTOMER_ID}); Card card = cu.cards->retrieve({CARD_ID}); stripe.customers.retrieveCard( {CUSTOMER_ID}, {CARD_ID}, function(card) {...} ); curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ/cards/card_103tJZ2eZvKYlo2CxOfJvLy0 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") card = customer.cards.retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") card = customer.cards.retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $card = $cu->cards->retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); Card card = cu.getCards().retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0");var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.retrieveCard( "cus_3tHwg1YkHpeHOJ", "card_103tJZ2eZvKYlo2CxOfJvLy0", function(err, card) { // asynchronously called } ); { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }#<Stripe::Card id=card_103tJZ2eZvKYlo2CxOfJvLy0 0x00000a> JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }<Card card id=card_103tJZ2eZvKYlo2CxOfJvLy0 at 0x00000a> JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }{ "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }com.stripe.model.Card JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }{ "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }
 

Updating a card

If you need to update only some card details, like the billing address or expiration date, you can do so without having to re-enter the full card details.

When you update a card, Stripe will automatically validate the card.

Arguments
address_city
optional
address_country
optional
address_line1
optional
address_line2
optional
address_state
optional
address_zip
optional
exp_month
optional
exp_year
optional
name
optional
Returns

Returns the card object.

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/cards/{CARD_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID}) card = customer.cards.retrieve({CARD_ID}) card.name = {NEW_NAME} card.save customer = stripe.Customer.retrieve({CUSTOMER_ID}) card = customer.cards.retrieve({CARD_ID}) card.name = {NEW_NAME} card.save() $customer = Stripe_Customer::retrieve({CUSTOMER_ID}); $card = $customer->cards->retrieve({CARD_ID})); $card->name = {NEW_NAME}; $card->save(); Customer cu = Customer.retrieve({CUSTOMER_ID}); Card card = cu.cards->retrieve({CARD_ID}); Map updateParams = new HashMap(); updateParams.put("name", {NEW_NAME}); card.update(updateParams); stripe.customers.updateCard({CUSTOMER_ID}, {CARD_ID}, { name: {NEW_NAME} }) curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ/cards/card_103tJZ2eZvKYlo2CxOfJvLy0 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d "name=Jane Austen"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") card = customer.cards.retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0") card.name = "Jane Austen" card.saveimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") card = customer.cards.retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0") card.name = "Jane Austen" card.save()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $card = $cu->cards->retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0"); $card->name = "Jane Austen"; $card->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); Card card = cu.getCards().retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0"); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("name", "Jane Austen"); card.update(updateParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.updateCard( "cus_3tHwg1YkHpeHOJ", "card_103tJZ2eZvKYlo2CxOfJvLy0", { name: "Jane Austen" }, function(err, card) { // asynchronously called } ); { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "Jane Austen", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }#<Stripe::Card id=card_103tJZ2eZvKYlo2CxOfJvLy0 0x00000a> JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "Jane Austen", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }<Card card id=card_103tJZ2eZvKYlo2CxOfJvLy0 at 0x00000a> JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "Jane Austen", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }{ "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "Jane Austen", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }com.stripe.model.Card JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "Jane Austen", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }{ "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3tHwg1YkHpeHOJ", "country": "US", "name": "Jane Austen", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }
 

Deleting cards

You can delete cards from a customer. If you delete a card that is currently a customer's default, the most recently added card will be used as the new default. If you delete the customer's last remaining card, the default_card attribute on the customer will become null.

Note that you may want to prevent customers on paid subscriptions from deleting all cards on file so that there is at least one default card for the next invoice payment attempt.

Arguments
id
required
customer
required
Returns

Returns the deleted card object.

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/cards/{CARD_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID}) customer.cards.retrieve({CARD_ID}).delete() customer = stripe.Customer.retrieve({CUSTOMER_ID}) customer.cards.retrieve({CARD_ID}).delete() $customer = Stripe_Customer::retrieve({CUSTOMER_ID}); $customer->cards->retrieve({CARD_ID})->delete(); Customer cu = Customer.retrieve({CUSTOMER_ID}); for(Card card : cu.getCards().getData()){ if(card.getId().equals({CARD_ID})){ card.delete(); break; } } stripe.customers.deleteCard({CUSTOMER_ID}, {CARD_ID}) curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ/cards/card_103tJZ2eZvKYlo2CxOfJvLy0 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X DELETErequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") customer.cards.retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0").delete()import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") customer.cards.retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0").delete()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $cu->cards->retrieve("card_103tJZ2eZvKYlo2CxOfJvLy0")->delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); for(Card card : cu.getCards().getData()){ if(card.getId().equals("card_103tJZ2eZvKYlo2CxOfJvLy0")){ card.delete(); break; } }var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.deleteCard( "cus_3tHwg1YkHpeHOJ", "card_103tJZ2eZvKYlo2CxOfJvLy0", function(err, confirmation) { // asynchronously called } ); { "deleted": true, "id": "card_103tJZ2eZvKYlo2CxOfJvLy0" }#<Stripe::Object id=card_103tJZ2eZvKYlo2CxOfJvLy0 0x00000a> JSON: { "deleted": true, "id": "card_103tJZ2eZvKYlo2CxOfJvLy0" }<Object object id=card_103tJZ2eZvKYlo2CxOfJvLy0 at 0x00000a> JSON: { "deleted": true, "id": "card_103tJZ2eZvKYlo2CxOfJvLy0" }{ "deleted": true, "id": "card_103tJZ2eZvKYlo2CxOfJvLy0" }com.stripe.model.Deletedcard JSON: { "deleted": true, "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "deletedcard" }{ "deleted": true, "id": "card_103tJZ2eZvKYlo2CxOfJvLy0" }
 

Listing cards

You can see a list of the customer's cards. Note that the 10 most recent cards are always available by default on the customer object. If you need more than those 10, you can use the limit and starting_after parameters to page through additional cards.

Arguments
id
required The ID of the customer whose cards will be retrieved
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
Returns

Returns a list of the customer's stored cards.

You can optionally request that the response include the total count of all cards for the customer. To do so, specify `include[]=total_count` in your request.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/cardsStripe::Customer.retrieve({CUSTOMER_ID}).cards.all()stripe.Customer.retrieve({CUSTOMER_ID}).cards.all()Stripe_Customer::retrieve({CUSTOMER_ID})->cards->all();Customer.retrieve({CUSTOMER_ID}).getCards().all();stripe.customers.listCards({CUSTOMER_ID}); curl https://api.stripe.com/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/cards?count=3 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Customer.retrieve("cu_103tHw2eZvKYlo2Cg7hGw3DB").cards.all(:count => 3)import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Customer.retrieve("cu_103tHw2eZvKYlo2Cg7hGw3DB").cards.all( count=3)require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Customer::retrieve("cu_103tHw2eZvKYlo2Cg7hGw3DB")->cards->all(array( 'count'=>3));Customer cu = Customer.retrieve("cu_103tHw2eZvKYlo2Cg7hGw3DB"); Map cardParams = new HashMap(); cardParams.put("count", 3); CustomerCardCollection cards = cu.getCards().all(cardParams); stripe.customers.listCards('cu_103tHw2eZvKYlo2Cg7hGw3DB', function(err, cards) { // asynchronously called }); { "object": "list", "url": "/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/cards", "has_more": false, "data": [ { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }, {...}, {...} ] } #<Stripe::ListObject:0x3fe634d74498> JSON: { "object": "list", "count": 3, "url": "/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/cards", "data": [ #<Stripe::Card id=card_103tJZ2eZvKYlo2CxOfJvLy0 0x00000a> JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }, #<Stripe::Card[...] ...>, #<Stripe::Card[...] ...> ] } { object: "list", url: "/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/cards", has_more: false, data: [ <Card card id=card_103tJZ2eZvKYlo2CxOfJvLy0 at 0x00000a> JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }, <stripe.Card[...] ...>, <stripe.Card[...] ...> ] } Array( "object" => "list", "url" => "/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/cards", "has_more" => false, "data" => Array( [0] => { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null } [1] => <Stripe_Card[...] ...> [2] => <Stripe_Card[...] ...> ) ) #<com.stripe.model.CardCollection id=#> JSON: { "data": [ com.stripe.model.Card JSON: { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }, #<com.stripe.model.Card[...] ...>, #<com.stripe.model.Card[...] ...> ], "has_more": false } { "object": "list", "url": "/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/cards", "has_more": false, "data": [ { "id": "card_103tJZ2eZvKYlo2CxOfJvLy0", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2018, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": null, "country": "US", "name": "hello@kitty.com", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": "pass", "address_line1_check": null, "address_zip_check": null }, {...}, {...} ] }
 

Subscriptions

Subscriptions allow you to charge a customer's card on a recurring basis. A subscription ties a customer to a particular plan you've created.

 

The subscription object

Attributes
id
string
object
string, value is "subscription"
cancel_at_period_end
boolean If the subscription has been canceled with the at_period_end flag set to true, cancel_at_period_end on the subscription will be true. You can use this attribute to determine whether a subscription that has a status of active is scheduled to be canceled at the end of the current period.
customer
plan
hash, plan object Hash describing the plan the customer is subscribed to
quantity
integer
start
timestamp Date the subscription started
status
string Possible values are trialing, active, past_due, canceled, or unpaid. A subscription still in its trial period is trialing and moves to active when the trial period is over. When payment to renew the subscription fails, the subscription becomes past_due. After Stripe has exhausted all payment retry attempts, the subscription ends up with a status of either canceled or unpaid depending on your retry settings. Note that when a subscription has a status of unpaid, no subsequent invoices will be attempted (invoices will be created, but then immediately automatically closed). After receiving updated card details from a customer, you may choose to reopen and pay their closed invoices.
application_fee_percent
decimal A positive decimal that represents the fee percentage of the subscription invoice amount that will be transferred to the application owner’s Stripe account each billing period.
canceled_at
timestamp If the subscription has been canceled, the date of that cancellation. If the subscription was canceled with cancel_at_period_end, canceled_at will still reflect the date of the initial cancellation request, not the end of the subscription period when the subscription is automatically moved to a canceled state.
current_period_end
timestamp End of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.
current_period_start
timestamp Start of the current period that the subscription has been invoiced for
discount
hash, discount object Describes the current discount applied to this subscription, if there is one. When billing, a discount applied to a subscription overrides a discount applied on a customer-wide basis.
ended_at
timestamp If the subscription has ended (either because it was canceled or because the customer was switched to a subscription to a new plan), the date the subscription ended
trial_end
timestamp If the subscription has a trial, the end of that trial.
trial_start
timestamp If the subscription has a trial, the beginning of that trial.
{ "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }#<Stripe::StripeObject id=sub_3tJat5ZqB1r5I1 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }<StripeObject subscription id=sub_3tJat5ZqB1r5I1 at 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }{ "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }com.stripe.model.StripeObject JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }{ "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }
 

Creating a new subscription

Creates a new subscription on an existing customer.

Arguments
plan
required The identifier of the plan to subscribe the customer to.
coupon
optional, default is nullnilNonenullnullnull The code of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription.
trial_end
optional, default is nullnilNonenullnullnull UTC integer timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately.
card
optional, default is nullnilNonenullnullnull The card can either be a token, like the ones returned by our Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobject containing a user's credit card details (with the options shown below). You must provide a card if the customer does not already have a valid card attached, and you are subscribing the customer for a plan that is not free. Passing card will create a new card, make it the customer default card, and delete the old customer default if one exists. If you want to add an additional card to use with subscriptions, instead use the card creation API to add the card and then the customer update API to set it as the default. Whenever you attach a card to a customer, Stripe will automatically validate the card.
quantity
optional, default is 111111 The quantity you'd like to apply to the subscription you're creating. For example, if your plan is $10/user/month, and your customer has 5 users, you could pass 5 as the quantity to have the customer charged $50 (5 x $10) monthly. If you update a subscription but don't change the plan ID (e.g. changing only the trial_end), the subscription will inherit the old subscription's quantity attribute unless you pass a new quantity parameter. If you update a subscription and change the plan ID, the new subscription will not inherit the quantity attribute and will default to 1 unless you pass a quantity parameter.
application_fee_percent
optional, default is nullnilNonenullnullnull A positive decimal (with at most two decimal places) between 1 and 100 that represents the percentage of the subscription invoice amount due each billing period (including any bundled invoice items) that will be transferred to the application owner’s Stripe account. The request must be made with an OAuth key in order to set an application fee percentage . For more information, see the application fees documentation.
Returns

The newly created subscription object if the call succeeded.

If the customer has no card or the attempted charge fails, this call returnsraisesraisesthrowsthrowsthrows an error (unless the specified plan is free or has a trial period).

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptionscustomer = Stripe::Customer.retrieve({CUSTOMER_ID}) customer.subscriptions.create({:plan => PLAN_ID}) customer = stripe.Customer.retrieve({CUSTOMER_ID}) customer.subscriptions.create(plan={PLAN_ID}) $customer = Stripe_Customer::retrieve({CUSTOMER_ID}); $customer.subscriptions->create(array("plan" => {PLAN_ID})); Customer cu = Customer.retrieve({CUSTOMER_ID}); Map params = new HashMap(); params.put("plan", {PLAN_ID}); cu.subscriptions->create(params); stripe.customers.createSubscription({CUSTOMER_ID}, { plan: {PLAN_ID} }); curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d plan=basicrequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") customer.subscriptions.create(:plan => "basic")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") customer.subscriptions.create(plan="basic")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $cu->subscriptions->create(array("plan" => "basic"));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); Map<String, Object> params = new HashMap<String, Object>(); params.put("plan", "basic"); cu.createSubscription(params)var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.createSubscription( "cus_3tHwg1YkHpeHOJ", {plan: "basic"}, function(err, subscription) { // asynchronously called } ); { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }#<Stripe::StripeObject id=sub_3tJat5ZqB1r5I1 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }<StripeObject subscription id=sub_3tJat5ZqB1r5I1 at 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }{ "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }com.stripe.model.StripeObject JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }{ "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }
 

Retrieving a customer's subscription

By default, you can see the 10 most recent active subscriptions stored on a customer directly on the customer object, but you can also retrieve details about a specific active subscription for a customer.

Arguments
id
required ID of subscription to retrieve.
customer
required
Returns

Returns the subscription object.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID}) subscription = customer.subscriptions.retrieve({SUBSCRIPTION_ID}) customer = stripe.Customer.retrieve({CUSTOMER_ID}) subscription = customer.subscriptions.retrieve({SUBSCRIPTION_ID}) $customer = Stripe_Customer::retrieve({CUSTOMER_ID}); $subscription = $customer->subscriptions->retrieve({SUBSCRIPTION_ID})); Customer cu = Customer.retrieve({CUSTOMER_ID}); Subscription subscription = cu.subscriptions->retrieve({SUBSCRIPTION_ID}); stripe.customers.retrieveSubscription( {CUSTOMER_ID}, {SUBSCRIPTION_ID}, function(subscription) {...} ); curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions/sub_3tJat5ZqB1r5I1 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") subscription = customer.subscriptions.retrieve("sub_3tJat5ZqB1r5I1")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") subscription = customer.subscriptions.retrieve("sub_3tJat5ZqB1r5I1")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $subscription = $cu->subscriptions->retrieve("sub_3tJat5ZqB1r5I1");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); Subscription subscription = cu.getSubscriptions().retrieve("sub_3tJat5ZqB1r5I1");var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.retrieveSubscription( "cus_3tHwg1YkHpeHOJ", "sub_3tJat5ZqB1r5I1", function(err, subscription) { // asynchronously called } ); { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }#<Stripe::StripeObject id=sub_3tJat5ZqB1r5I1 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }<StripeObject subscription id=sub_3tJat5ZqB1r5I1 at 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }{ "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }com.stripe.model.StripeObject JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }{ "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }
 

Updating a Subscription

Updates an existing subscription on a customer to match the specified parameters. When changing plans or quantities, we will optionally prorate the price we charge next month to make up for any price changes.

Arguments
plan
optional The identifier of the plan to update the subscription to. If omitted, the subscription will not change plans.
coupon
optional, default is nullnilNonenullnullnull The code of the coupon to apply to the customer if you would like to apply it at the same time as creating the subscription.
prorate
optional, default is true Flag telling us whether to prorate switching plans during a billing cycle.
trial_end
optional, default is nullnilNonenullnullnull UTC integer timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately.
card
optional, default is nullnilNonenullnullnull The card can either be a token, like the ones returned by our Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobject containing a user's credit card details (with the options shown below). You must provide a card if the customer does not already have a valid card attached, and you are subscribing the customer for a plan that is not free. Passing card will create a new card, make it the customer default card, and delete the old customer default if one exists. If you want to add an additional card to use with subscriptions, instead use the card creation API to add the card and then the customer update API to set it as the default. Whenever you attach a card to a customer, Stripe will automatically validate the card.
quantity
optional, default is 111111 The quantity you'd like to apply to the subscription you're updating. For example, if your plan is $10/user/month, and your customer has 5 users, you could pass 5 as the quantity to have the customer charged $50 (5 x $10) monthly. If you update a subscription but don't change the plan ID (e.g. changing only the trial_end), the subscription will inherit the old subscription's quantity attribute unless you pass a new quantity parameter. If you update a subscription and change the plan ID, the new subscription will not inherit the quantity attribute and will default to 1 unless you pass a quantity parameter.
application_fee_percent
optional, default is nullnilNonenullnullnull A positive decimal (with at most two decimal places) between 1 and 100 that represents the percentage of the subscription invoice amount due each billing period (including any bundled invoice items) that will be transferred to the application owner’s Stripe account. The request must be made with an OAuth key in order to set an application fee percentage . For more information, see the application fees documentation.

By default, we prorate subscription changes. For example, if a customer signs up on May 1 for a $10 plan, she'll be billed $10 immediately. If she then switches to a $20 plan on May 15, on June 1 she'll be billed $25 ($20 for a renewal of her subscription and a $5 prorating adjustment for the previous month). Similarly, a downgrade will generate a credit to be applied to the next invoice. We also prorate when you make quantity changes. Switching plans does not change the billing date or generate an immediate charge unless you're switching between different intervals (e.g. monthly to yearly), in which case we apply a credit for the time unused on the old plan and charge for the new plan starting right away, resetting the billing date.

If you'd like to charge for an upgrade immediately, just pass prorate as true as usual, and then invoice the customer as soon as you make the subscription change. That'll collect the proration adjustments into a new invoice, and Stripe will automatically attempt to pay the invoice.

If you don't want to prorate at all, set the prorate option to falsefalsefalsefalsefalsefalse and the customer would be billed $10 on May 1 and $20 on June 1. Similarly, if you set prorate to false when switching between different billing intervals (monthly to yearly, for example), we won't generate any credits for the old subscription's unused time, although we will still reset the billing date and bill immediately for the new subscription.

Returns

The newly created subscription object if the call succeeded.

If the customer has no card or the attempted charge fails, this call returnsraisesraisesthrowsthrowsthrows an error (unless the specified plan is free or has a trial period).

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID}) subscription = customer.subscriptions.retrieve({SUBSCRIPTION_ID}) subscription.plan = {PLAN_ID} subscription.save customer = stripe.Customer.retrieve({CUSTOMER_ID}) subscription = customer.subscriptions.retrieve({SUBSCRIPTION_ID}) subscription.plan = {PLAN_ID} subscription.save() $customer = Stripe_Customer::retrieve({CUSTOMER_ID}); $subscription = $customer->subscriptions->retrieve({SUBSCRIPTION_ID})); $subscription->plan = {PLAN_ID}; $subscription->save(); Customer cu = Customer.retrieve({CUSTOMER_ID}); Subscription subscription = cu.subscriptions->retrieve({SUBSCRIPTION_ID}); Map updateParams = new HashMap(); updateParams.put("plan", {PLAN_ID}); subscription.update(updateParams); stripe.customers.updateSubscription({CUSTOMER_ID}, {SUBSCRIPTION_ID}, { plan: {PLAN_ID} }) curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions/sub_3tJat5ZqB1r5I1 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d plan=basicrequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") subscription = customer.subscriptions.retrieve("sub_3tJat5ZqB1r5I1") subscription.plan = "basic" subscription.saveimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") subscription = customer.subscriptions.retrieve("sub_3tJat5ZqB1r5I1") subscription.plan = "basic" subscription.save()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $subscription = $cu->subscriptions->retrieve("sub_3tJat5ZqB1r5I1"); $subscription->plan = "basic"; $subscription->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); Subscription subscription = cu.getSubscriptions().retrieve("sub_3tJat5ZqB1r5I1"); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("plan", "basic"); subscription.update(updateParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.updateSubscription( "cus_3tHwg1YkHpeHOJ", "sub_3tJat5ZqB1r5I1", { plan: "basic" }, function(err, subscription) { // asynchronously called } ); { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }#<Stripe::StripeObject id=sub_3tJat5ZqB1r5I1 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }<StripeObject subscription id=sub_3tJat5ZqB1r5I1 at 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }{ "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }com.stripe.model.StripeObject JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }{ "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }
 

Canceling a Customer's Subscription

Cancels a customer's subscription. If you set the at_period_end parameter to true, the subscription will remain active until the end of the period, at which point it will be canceled and not renewed. By default, the subscription is terminated immediately. In either case, the customer will not be charged again for the subscription. Note, however, that any pending invoice items that you've created will still be charged for at the end of the period unless manually deleted. If you've set the subscription to cancel at period end, any pending prorations will also be left in place and collected at the end of the period, but if the subscription is set to cancel immediately, pending prorations will be removed.

By default, all unpaid invoices for the customer will be closed upon subscription cancellation. We do this in order to prevent unexpected payment retries once the customer has canceled a subscription. However, you can reopen the invoices manually after subscription cancellation to have us proceed with automatic retries, or you could even re-attempt payment yourself on all unpaid invoices before allowing the customer to cancel the subscription at all.

Arguments
at_period_end
optional, default is false A flag that if set to true will delay the cancellation of the subscription until the end of the current period.
Returns

The canceled subscription object. Its subscription status will be set to "canceled" unless you've set at_period_end to true when canceling, in which case the status will remain "active" but the cancel_at_period_end attribute will change to true.

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID}) customer.subscriptions.retrieve({SUBSCRIPTION_ID}).delete() customer = stripe.Customer.retrieve({CUSTOMER_ID}) customer.subscriptions.retrieve({SUBSCRIPTION_ID}).delete() $customer = Stripe_Customer::retrieve({CUSTOMER_ID}); $customer->subscriptions->retrieve({SUBSCRIPTION_ID})->cancel(); Customer cu = Customer.retrieve({CUSTOMER_ID}); for(Subscription subscription : cu.getSubscriptions().getData()){ if(subscription.getId().equals({SUBSCRIPTION_ID})){ subscription.cancel(null); break; } } stripe.customers.cancelSubscription({CUSTOMER_ID}, {SUBSCRIPTION_ID}) curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions/sub_3tJat5ZqB1r5I1 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X DELETErequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") customer.subscriptions.retrieve("sub_3tJat5ZqB1r5I1").delete()import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" customer = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") customer.subscriptions.retrieve("sub_3tJat5ZqB1r5I1").delete()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $cu->subscriptions->retrieve("sub_3tJat5ZqB1r5I1")->cancel();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); for(Subscription subscription : cu.getSubscriptions().getData()){ if(subscription.getId().equals("sub_3tJat5ZqB1r5I1")){ subscription.cancel(null); break; } }var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.customers.cancelSubscription( "cus_3tHwg1YkHpeHOJ", "sub_3tJat5ZqB1r5I1", function(err, confirmation) { // asynchronously called } ); { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }#<Stripe::StripeObject id=sub_3tJat5ZqB1r5I1 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }<StripeObject subscription id=sub_3tJat5ZqB1r5I1 at 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }{ "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }com.stripe.model.Deletedsubscription JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "deletedsubscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }{ "id": "sub_3tJat5ZqB1r5I1", "plan": "basic", "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }
 

Listing subscriptions

You can see a list of the customer's active subscriptions. Note that the 10 most recent active subscriptions are always available by default on the customer object. If you need more than those 10, you can use the limit and starting_after parameters to page through additional subscriptions.

Arguments
id
required The ID of the customer whose subscriptions will be retrieved
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
Returns

Returns a list of the customer's active subscriptions.

You can optionally request that the response include the total count of all subscriptions for the customer. To do so, specify `include[]=total_count` in your request.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptionsStripe::Customer.retrieve({CUSTOMER_ID}).subscriptions.all()stripe.Customer.retrieve({CUSTOMER_ID}).subscriptions.all()Stripe_Customer::retrieve({CUSTOMER_ID})->subscriptions->all();Customer.retrieve({CUSTOMER_ID}).getSubscriptions().all();stripe.customers.listSubscriptions({CUSTOMER_ID}); curl https://api.stripe.com/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/subscriptions?count=3 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Customer.retrieve("cu_103tHw2eZvKYlo2Cg7hGw3DB").subscriptions.all(:count => 3)import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Customer.retrieve("cu_103tHw2eZvKYlo2Cg7hGw3DB").subscriptions.all( count=3)require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Customer::retrieve("cu_103tHw2eZvKYlo2Cg7hGw3DB")->subscriptions->all(array( 'count'=>3));Customer cu = Customer.retrieve("cu_103tHw2eZvKYlo2Cg7hGw3DB"); Map subscriptionParams = new HashMap(); subscriptionParams.put("count", 3); CustomerSubscriptionCollection subscriptions = cu.getSubscriptions().all(subscriptionParams); stripe.customers.listSubscriptions('cu_103tHw2eZvKYlo2Cg7hGw3DB', function(err, subscriptions) { // asynchronously called }); { "object": "list", "url": "/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/subscriptions", "has_more": false, "data": [ { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }, {...}, {...} ] } #<Stripe::ListObject:0x3fe634d74498> JSON: { "object": "list", "count": 3, "url": "/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/subscriptions", "data": [ #<Stripe::StripeObject id=sub_3tJat5ZqB1r5I1 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }, #<Stripe::Subscription[...] ...>, #<Stripe::Subscription[...] ...> ] } { object: "list", url: "/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/subscriptions", has_more: false, data: [ <StripeObject subscription id=sub_3tJat5ZqB1r5I1 at 0x00000a> JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }, <stripe.Subscription[...] ...>, <stripe.Subscription[...] ...> ] } Array( "object" => "list", "url" => "/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/subscriptions", "has_more" => false, "data" => Array( [0] => { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null } [1] => <Stripe_Subscription[...] ...> [2] => <Stripe_Subscription[...] ...> ) ) #<com.stripe.model.SubscriptionCollection id=#> JSON: { "data": [ com.stripe.model.StripeObject JSON: { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }, #<com.stripe.model.Subscription[...] ...>, #<com.stripe.model.Subscription[...] ...> ], "has_more": false } { "object": "list", "url": "/v1/customers/cu_103tHw2eZvKYlo2Cg7hGw3DB/subscriptions", "has_more": false, "data": [ { "id": "sub_3tJat5ZqB1r5I1", "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "object": "subscription", "start": 1398046478, "status": "active", "customer": "cus_3tHwg1YkHpeHOJ", "cancel_at_period_end": false, "current_period_start": 1398046478, "current_period_end": 1400638478, "ended_at": null, "trial_start": null, "trial_end": null, "canceled_at": null, "quantity": 1, "application_fee_percent": null, "discount": null }, {...}, {...} ] }
 

Plans

A subscription plan contains the pricing information for different products and feature levels on your site. For example, you might have a $10/month plan for basic features and a different $20/month plan for premium features.

 

The plan object

Attributes
id
string
object
string, value is "plan"
livemode
boolean
amount
positive integer or zero The amount in cents to be charged on the interval specified
created
timestamp
currency
currency Currency in which subscription will be charged
interval
interval string One of week, month or year. The frequency with which a subscription should be billed.
interval_count
positive integer The number of intervals (specified in the interval property) between each subscription billing. For example, interval=month and interval_count=3 bills every 3 months.
name
string Display name of the plan
metadata
metadata hash A set of key/value pairs that you can attach to a plan object. It can be useful for storing additional information about the plan in a structured format.
trial_period_days
positive integer Number of trial period days granted when subscribing a customer to this plan. Null if the plan has no trial period.
statement_description
string Extra information about a charge for the customer’s credit card statement.
{ "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }#<Stripe::Plan id=gold21323 0x00000a> JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }<Plan plan id=gold21323 at 0x00000a> JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }{ "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }com.stripe.model.Plan JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }{ "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }
 

Creating plans

You can create plans easily via the plan management page of the Stripe dashboard. Plan creation is also accessible via the API if you need to create plans on the fly.

Arguments
id
required Unique string of your choice that will be used to identify this plan when subscribing a customer. This could be an identifier like "gold" or a primary key from your own database.
amount
required A positive integer in cents (or 0 for a free plan) representing how much to charge (on a recurring basis).
currency
required 3-letter ISO code for currency.
interval
required Specifies billing frequency. Either week, month or year.
interval_count
optional, default is 1 The number of intervals between each subscription billing. For example, interval=month and interval_count=3 bills every 3 months. Maximum of one year interval allowed (1 year, 12 months, or 52 weeks).
name
required Name of the plan, to be displayed on invoices and in the web interface.
trial_period_days
optional Specifies a trial period in (an integer number of) days. If you include a trial period, the customer won't be billed for the first time until the trial period ends. If the customer cancels before the trial period is over, she'll never be billed at all.
metadata
optional, default is { }{ }{ }{ }{ }{ } A set of key/value pairs that you can attach to a plan object. It can be useful for storing additional information about the plan in a structured format.
statement_description
optional, default is nullnilNonenullnullnull An arbitrary string to be displayed on your customers' credit card statements (alongside your company name) for charges created by this plan. This may be up to 15 characters. As an example, if your website is RunClub and you specify Silver Plan, the user will see RUNCLUB SILVER PLAN. The statement description may not include <>"' characters. While most banks display this information consistently, some may display it incorrectly or not at all.
POST https://api.stripe.com/v1/plansStripe::Plan.createstripe.Plan.create()Stripe_Plan::create();Plan.create();stripe.plans.create(); curl https://api.stripe.com/v1/plans \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d amount=2000 \ -d interval=month \ -d "name=Amazing Gold Plan" \ -d currency=usd \ -d id=goldrequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Plan.create( :amount => 2000, :interval => 'month', :name => 'Amazing Gold Plan', :currency => 'usd', :id => 'gold' )import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Plan.create( amount=2000, interval='month', name='Amazing Gold Plan', currency='usd', id='gold')require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Plan::create(array( "amount" => 2000, "interval" => "month", "name" => "Amazing Gold Plan", "currency" => "usd", "id" => "gold") );Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> planParams = new HashMap<String, Object>(); planParams.put("amount", 2000); planParams.put("interval", "month"); planParams.put("name", "Amazing Gold Plan"); planParams.put("currency", "usd"); planParams.put("id", "gold"); Plan.create(planParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.plans.create({ amount: 2000, interval: "month", name: "Amazing Gold Plan", currency: "usd", id: "gold" }, function(err, plan) { // asynchronously called }); { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }#<Stripe::Plan id=gold21323 0x00000a> JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }<Plan plan id=gold21323 at 0x00000a> JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }{ "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }com.stripe.model.Plan JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }{ "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }
 

Retrieving a Plan

Retrieves the plan with the given ID.

Arguments
id
required The ID of the desired plan.
Returns

Returns a plan if a valid plan ID was provided. ReturnsRaisesRaisesThrowsThrowsThrows an error otherwise.

GET https://api.stripe.com/v1/plans/{PLAN_ID}Stripe::Plan.retrieve({PLAN_ID})stripe.Plan.retrieve({PLAN_ID})Stripe_Plan::retrieve({PLAN_ID});Plan.retrieve({PLAN_ID});stripe.plans.retrieve({PLAN_ID}); curl https://api.stripe.com/v1/plans/gold21323 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Plan.retrieve("gold21323")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Plan.retrieve("gold21323")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Plan::retrieve("gold21323");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Plan.retrieve("gold21323");var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.plans.retrieve("gold21323", function(err, plan) { // asynchronously called }); { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }#<Stripe::Plan id=gold21323 0x00000a> JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }<Plan plan id=gold21323 at 0x00000a> JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }{ "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }com.stripe.model.Plan JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }{ "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }
 

Updating a plan

Updates the name of a plan. Other plan details (price, interval, etc.) are, by design, not editable.

Arguments
name
optional Name of the plan, to be displayed on invoices and in the web interface.
metadata
optional, default is { }{ }{ }{ }{ }{ } A set of key/value pairs that you can attach to a plan object. It can be useful for storing additional information about the plan in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to nullnilNonenullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnull, then save.
statement_description
optional, default is nullnilNonenullnullnull An arbitrary string to be displayed on your customers' credit card statements (alongside your company name) for charges created by this plan. This may be up to 15 characters. As an example, if your website is RunClub and you specify Silver Plan, the user will see RUNCLUB SILVER PLAN. The statement description may not include <>"' characters. While most banks display this information consistently, some may display it incorrectly or not at all. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
Returns

The updated plan object is returned upon success. Otherwise, this call returnsraisesraisesthrowsthrowsthrows an error.

POST https://api.stripe.com/v1/plans/{PLAN_ID}p = Stripe::Plan.retrieve({PLAN_ID}) p.name = {NAME} ... p.save p = stripe.Plan.retrieve({PLAN_ID}) p.name = {NAME} ... p.save() $p = Stripe_Plan::retrieve({PLAN_ID}); $p->name = {NAME}; ... $p->save(); Plan p = Plan.retrieve({PLAN_ID}); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("name", {NAME}); ... p.update(updateParams);stripe.plans.update({PLAN_ID}, { name: {NAME} }); curl https://api.stripe.com/v1/plans/gold21323 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d "name=New plan name"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" p = Stripe::Plan.retrieve("gold21323") p.name = "New plan name" p.saveimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" p = stripe.Plan.retrieve("gold21323") p.name = "New plan name" p.save()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $p = Stripe_Plan::retrieve("gold21323"); $p->name = "New plan name"; $p->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Plan p = Plan.retrieve("gold21323"); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("name", "New plan name"); p.update(updateParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.plans.update("gold21323", { name: "New plan name" }, function(err, plan) { // asynchronously called }); { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }#<Stripe::Plan id=gold21323 0x00000a> JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }<Plan plan id=gold21323 at 0x00000a> JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }{ "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }com.stripe.model.Plan JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }{ "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }
 

Deleting a plan

You can delete plans via the plan management page of the Stripe dashboard. However, deleting a plan does not affect any current subscribers to the plan; it merely means that new subscribers can't be added to that plan. You can also delete plans via the API.

Arguments
id
required The identifier of the plan to be deleted.
Returns

An object with the deleted plan's ID and a deleted flag upon success. Otherwise, this call returnsraisesraisesthrowsthrowsthrows an error, such as if the plan has already been deleted.

DELETE https://api.stripe.com/v1/plans/{PLAN_ID}plan = Stripe::Plan.retrieve({PLAN_ID}) plan.delete plan = stripe.Plan.retrieve({PLAN_ID}) plan.delete() $plan = Stripe_Plan::retrieve({PLAN_ID}); $plan->delete(); Plan plan = Plan.retrieve({PLAN_ID}); plan.delete(); stripe.plans.del({PLAN_ID}); curl https://api.stripe.com/v1/plans/gold21323 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X DELETErequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" plan = Stripe::Plan.retrieve("gold21323") plan.deleteimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" plan = stripe.Plan.retrieve("gold21323") plan.delete()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $plan = Stripe_Plan::retrieve("gold21323"); $plan->delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Plan plan = Plan.retrieve("gold21323"); plan.delete();var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.plans.del( "gold21323", function(err, confirmation) { // asynchronously called } ); { "deleted": true, "id": "gold21323" }#<Stripe::Object id=gold21323 0x00000a> JSON: { "deleted": true, "id": "gold21323" }<Object object id=gold21323 at 0x00000a> JSON: { "deleted": true, "id": "gold21323" }{ "deleted": true, "id": "gold21323" }com.stripe.model.Object JSON: { "deleted": true, "id": "gold21323" }{ "deleted": true, "id": "gold21323" }
 

List all Plans

Returns a list of your plans.

Arguments
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
Returns

A dictionaryhashdictionaryassociative arrayMapobject with a data property that contains an array of up to limit plans, starting after plan starting_after. Each entry in the array is a separate plan object. If no more plans are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrow an error.

You can optionally request that the response include the total count of all plans. To do so, specify `include[]=total_count` in your request.

GET https://api.stripe.com/v1/plansStripe::Plan.allstripe.Plan.all()Stripe_Plan::all();Plan.all(Map options);stripe.plans.list(); curl https://api.stripe.com/v1/plans \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Plan.allimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Plan.all()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Plan::all();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Plan.all(new HashMap<String, Object>());var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.plans.list(function(err, plans) { // asynchronously called }); { "object": "list", "url": "/v1/plans", "has_more": false, "data": [ { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, {...}, {...} ] } #<Stripe::ListObject:0x3fe634d74498> JSON: { "object": "list", "count": 3, "url": "/v1/plans", "data": [ #<Stripe::Plan id=gold21323 0x00000a> JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, #<Stripe::Plan[...] ...>, #<Stripe::Plan[...] ...> ] } { object: "list", url: "/v1/plans", has_more: false, data: [ <Plan plan id=gold21323 at 0x00000a> JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, <stripe.Plan[...] ...>, <stripe.Plan[...] ...> ] } Array( "object" => "list", "url" => "/v1/plans", "has_more" => false, "data" => Array( [0] => { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null } [1] => <Stripe_Plan[...] ...> [2] => <Stripe_Plan[...] ...> ) ) #<com.stripe.model.PlanCollection id=#> JSON: { "data": [ com.stripe.model.Plan JSON: { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, #<com.stripe.model.Plan[...] ...>, #<com.stripe.model.Plan[...] ...> ], "has_more": false } { "object": "list", "url": "/v1/plans", "has_more": false, "data": [ { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, {...}, {...} ] }
 

Coupons

A coupon contains information about a percent-off discount you might want to apply to a customer. Coupons only apply to invoices created for recurring subscriptions and invoice items; they do not apply to one-off charges.

 

The coupon object

Attributes
id
string
object
string, value is "coupon"
livemode
boolean
created
timestamp
duration
coupon duration string One of forever, once, and repeating. Describes how long a customer who applies this coupon will get the discount.
amount_off
positive integer Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer.
currency
currency If amount_off has been set, the currency of the amount to take off.
duration_in_months
positive integer If duration is repeating, the number of months the coupon applies. Null if coupon duration is forever or once.
max_redemptions
positive integer Maximum number of times this coupon can be redeemed, in total, before it is no longer valid.
metadata
metadata hash A set of key/value pairs that you can attach to a coupon object. It can be useful for storing additional information about the coupon in a structured format.
percent_off
positive integer Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. For example, a coupon with percent_off of 50 will make a $100 invoice $50 instead.
redeem_by
timestamp Date after which the coupon can no longer be redeemed
times_redeemed
positive integer or zero Number of times this coupon has been applied to a customer.
valid
boolean Taking account of the above properties, whether this coupon can still be applied to a customer
{ "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }#<Stripe::Coupon id=50-pc-forever-once 0x00000a> JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }<Coupon coupon id=50-pc-forever-once at 0x00000a> JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }{ "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }com.stripe.model.Coupon JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }{ "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }
 

Creating coupons

You can create coupons easily via the coupon management page of the Stripe dashboard. Coupon creation is also accessible via the API if you need to create coupons on the fly.

A coupon has either a percent_off or an amount_off and currency. If you set an amount_off, that amount will be subtracted from any invoice's subtotal. For example, an invoice with a subtotal of $10 will have a final total of $0 if a coupon with an amount_off of 2000 is applied to it and an invoice with a subtotal of $30 will have a final total of $10 if a coupon with an amount_off of 2000 is applied to it.

Arguments
id
optional Unique string of your choice that will be used to identify this coupon when applying it a customer. This is often a specific code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you can leave the ID blank and we’ll generate a random code for you.
duration
required Specifies how long the discount will be in effect. Can be forever, once, or repeating.
amount_off
optional A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed)
currency
optional Currency of the amount_off parameter (required if amount_off is passed)
duration_in_months
optional required only if duration is repeating If duration is repeating, a positive integer that specifies the number of months the discount will be in effect
max_redemptions
optional A positive integer specifying the number of times the coupon can be redeemed before it’s no longer valid. For example, you might have a 50% off coupon that the first 20 readers of your blog can use.
metadata
optional A set of key/value pairs that you can attach to a coupon object. It can be useful for storing additional information about the coupon in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
percent_off
optional A positive integer between 1 and 100 that represents the discount the coupon will apply (required if amount_off is not passed)
redeem_by
optional UTC timestamp specifying the last time at which the coupon can be redeemed. After the redeem_by date, the coupon can no longer be applied to new customers.
Returns

Returns the coupon object.

POST https://api.stripe.com/v1/couponsStripe::Coupon.createstripe.Coupon.create()Stripe_Coupon::create();Coupon.create();stripe.coupons.create(); curl https://api.stripe.com/v1/coupons \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d percent_off=25 \ -d duration=repeating \ -d duration_in_months=3 \ -d id=25OFFrequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Coupon.create( :percent_off => 25, :duration => 'repeating', :duration_in_months => 3, :id => '25OFF' )import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Coupon.create( percent_off=25, duration='repeating', duration_in_months=3, id='25OFF')require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Coupon::create(array( "percent_off" => 25, "duration" => "repeating", "duration_in_months" => 3, "id" => "25OFF") );Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> couponParams = new HashMap<String, Object>(); couponParams.put("percent_off", 25); couponParams.put("duration", "repeating"); couponParams.put("duration_in_months", 3); couponParams.put("id", "25OFF"); Coupon.create(couponParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.coupons.create({ percent_off: 25, duration: 'repeating', duration_in_months: 3, id: '25OFF' }); { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }#<Stripe::Coupon id=50-pc-forever-once 0x00000a> JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }<Coupon coupon id=50-pc-forever-once at 0x00000a> JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }{ "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }com.stripe.model.Coupon JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }{ "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }
 

Retrieving a Coupon

Retrieves the coupon with the given ID.

Arguments
id
required The ID of the desired coupon.
Returns

Returns a coupon if a valid coupon ID was provided. ReturnsRaisesRaisesThrowsThrowsThrows an error otherwise.

GET https://api.stripe.com/v1/coupons/{COUPON_ID}Stripe::Coupon.retrieve({COUPON_ID})stripe.Coupon.retrieve({COUPON_ID})Stripe_Coupon::retrieve({COUPON_ID});Coupon.retrieve({COUPON_ID});stripe.coupons.retrieve({COUPON_ID}); curl https://api.stripe.com/v1/coupons/50-pc-forever-once \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Coupon.retrieve("50-pc-forever-once")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Coupon.retrieve("50-pc-forever-once")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Coupon::retrieve("50-pc-forever-once");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Coupon.retrieve("50-pc-forever-once");var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.coupons.retrieve("50-pc-forever-once", function(err, coupon) { // asynchronously called }); { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }#<Stripe::Coupon id=50-pc-forever-once 0x00000a> JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }<Coupon coupon id=50-pc-forever-once at 0x00000a> JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }{ "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }com.stripe.model.Coupon JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }{ "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }
 

Deleting a coupon

You can delete coupons via the coupon management page of the Stripe dashboard. However, deleting a coupon does not affect any customers who have already applied the coupon; it means that new customers can't redeem the coupon. You can also delete coupons via the API.

Arguments
id
required The identifier of the coupon to be deleted.
Returns

An object with the deleted coupon's ID and a deleted flag upon success. Otherwise, this call returnsraisesraisesthrowsthrowsthrows an error, such as if the coupon has already been deleted.

DELETE https://api.stripe.com/v1/coupons/{COUPON_ID}cpn = Stripe::Coupon.retrieve({COUPON_ID}) cpn.delete cpn = stripe.Coupon.retrieve({COUPON_ID}) cpn.delete() $cpn = Stripe_Coupon::retrieve({COUPON_ID}); $cpn->delete(); Coupon cpn = Coupon.retrieve({COUPON_ID}); cpn.delete(); stripe.coupons.del({COUPON_ID}) curl https://api.stripe.com/v1/coupons/50-pc-forever-once \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X DELETErequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" cpn = Stripe::Coupon.retrieve("50-pc-forever-once") cpn.deleteimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" cpn = stripe.Coupon.retrieve("50-pc-forever-once") cpn.delete()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cpn = Stripe_Coupon::retrieve("50-pc-forever-once"); $cpn->delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Coupon cpn = Coupon.retrieve("50-pc-forever-once"); cpn.delete();var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.coupons.del("50-pc-forever-once") { "deleted": true, "id": "50-pc-forever-once" }#<Stripe::Object id=50-pc-forever-once 0x00000a> JSON: { "deleted": true, "id": "50-pc-forever-once" }<Object object id=50-pc-forever-once at 0x00000a> JSON: { "deleted": true, "id": "50-pc-forever-once" }{ "deleted": true, "id": "50-pc-forever-once" }com.stripe.model.Object JSON: { "deleted": true, "id": "50-pc-forever-once" }{ "deleted": true, "id": "50-pc-forever-once" }
 

List all Coupons

Returns a list of your coupons.

Arguments
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
Returns

A dictionaryhashdictionaryassociative arrayMapobject with a data property that contains an array of up to limit coupons, starting after coupon starting_after. Each entry in the array is a separate coupon object. If no more coupons are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrow an error.

You can optionally request that the response include the total count of all coupons. To do so, specify `include[]=total_count` in your request.

GET https://api.stripe.com/v1/couponsStripe::Coupon.allstripe.Coupon.all()Stripe_Coupon::all();Coupon.all(Map options);stripe.coupons.list(); curl https://api.stripe.com/v1/coupons \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Coupon.allimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Coupon.all()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Coupon::all();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Coupon.all(new HashMap<String, Object>());var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.coupons.list(); { "object": "list", "url": "/v1/coupons", "has_more": false, "data": [ { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, {...}, {...} ] } #<Stripe::ListObject:0x3fe634d74498> JSON: { "object": "list", "count": 3, "url": "/v1/coupons", "data": [ #<Stripe::Coupon id=50-pc-forever-once 0x00000a> JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, #<Stripe::Coupon[...] ...>, #<Stripe::Coupon[...] ...> ] } { object: "list", url: "/v1/coupons", has_more: false, data: [ <Coupon coupon id=50-pc-forever-once at 0x00000a> JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, <stripe.Coupon[...] ...>, <stripe.Coupon[...] ...> ] } Array( "object" => "list", "url" => "/v1/coupons", "has_more" => false, "data" => Array( [0] => { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } } [1] => <Stripe_Coupon[...] ...> [2] => <Stripe_Coupon[...] ...> ) ) #<com.stripe.model.CouponCollection id=#> JSON: { "data": [ com.stripe.model.Coupon JSON: { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, #<com.stripe.model.Coupon[...] ...>, #<com.stripe.model.Coupon[...] ...> ], "has_more": false } { "object": "list", "url": "/v1/coupons", "has_more": false, "data": [ { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, {...}, {...} ] }
 

Discounts

A 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.

 

The discount object

Attributes
object
string, value is "discount"
coupon
hash, coupon object Hash describing the coupon applied to create this discount
customer
start
timestamp Date that the coupon was applied
end
timestamp If the coupon has a duration of once or repeating, the date that this discount will end. If the coupon used has a forever duration, this attribute will be null.
subscription
string The subscription that this coupon is applied to, if it is applied to a particular subscription
{ "coupon": { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, "start": 1391694761, "object": "discount", "customer": "cus_3tHwg1YkHpeHOJ", "subscription": null, "end": 1399384361 }#<Stripe::Discount 0x00000a> JSON: { "coupon": { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, "start": 1391694761, "object": "discount", "customer": "cus_3tHwg1YkHpeHOJ", "subscription": null, "end": 1399384361 }<Discount discount at 0x00000a> JSON: { "coupon": { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, "start": 1391694761, "object": "discount", "customer": "cus_3tHwg1YkHpeHOJ", "subscription": null, "end": 1399384361 }{ "coupon": { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, "start": 1391694761, "object": "discount", "customer": "cus_3tHwg1YkHpeHOJ", "subscription": null, "end": 1399384361 }com.stripe.model.Discount JSON: { "coupon": { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, "start": 1391694761, "object": "discount", "customer": "cus_3tHwg1YkHpeHOJ", "subscription": null, "end": 1399384361 }{ "coupon": { "id": "50-pc-forever-once", "created": 1397741615, "percent_off": 50, "amount_off": null, "currency": "usd", "object": "coupon", "livemode": false, "duration": "forever", "redeem_by": 1397748842, "max_redemptions": null, "times_redeemed": 0, "duration_in_months": null, "valid": false, "metadata": { } }, "start": 1391694761, "object": "discount", "customer": "cus_3tHwg1YkHpeHOJ", "subscription": null, "end": 1399384361 }
 

Deleting a Customer-wide Discount

Removes the currently applied discount on a customer.

Returns

An object with a deleted flag set to true upon success. This call returnsraisesraisesthrowsthrowsthrows an error otherwise, such as if no discount exists on this customer.

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/discountcu = Stripe::Customer.retrieve({CUSTOMER_ID}) cu.delete_discount cu = stripe.Customer.retrieve({CUSTOMER_ID}) cu.delete_discount() $cu = Stripe_Customer::retrieve({CUSTOMER_ID}); $cu->deleteDiscount(); Customer cu = Customer.retrieve({CUSTOMER_ID}); cu.deleteDiscount(); stripe.customers.deleteDiscount({CUSTOMER_ID}); curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ/discount \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X DELETErequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" cu = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") cu.delete_discountimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" cu = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") cu.delete_discount()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $cu->deleteDiscount();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); cu.deleteDiscount();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; stripe.customers.deleteDiscount("cus_3tHwg1YkHpeHOJ", function(err, confirmation) { // asynchronously called }); { "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }#<Stripe::Object id=di_103Rm82eZvKYlo2CH0he3vGX 0x00000a> JSON: { "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }<Object object id=di_103Rm82eZvKYlo2CH0he3vGX at 0x00000a> JSON: { "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }{ "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }com.stripe.model.Object JSON: { "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }{ "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }
 

Deleting a Subscription Discount

Removes the currently applied discount on a subscription.

Returns

An object with a deleted flag set to true upon success. This call returnsraisesraisesthrowsthrowsthrows an error otherwise, such as if no discount exists on this subscription.

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}/discountcu = Stripe::Customer.retrieve({CUSTOMER_ID}) cu.subscriptions.retrieve({SUBSCRIPTION_ID}).delete_discount() cu = stripe.Customer.retrieve({CUSTOMER_ID}) cu.subscriptions.retrieve({SUBSCRIPTION_ID}).delete_discount() $cu = Stripe_Customer::retrieve({CUSTOMER_ID}); $cu->subscriptions->retrieve({SUBSCRIPTION_ID})->deleteDiscount(); Customer cu = Customer.retrieve({CUSTOMER_ID}); cu.subscriptions.retrieve({SUBSCRIPTION_ID}).deleteDiscount(); stripe.customers.deleteSubscriptionDiscount({CUSTOMER_ID}, {SUBSCRIPTION_ID}); curl https://api.stripe.com/v1/customers/cus_3tHwg1YkHpeHOJ/subscriptions/sub_3tJat5ZqB1r5I1/discount \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X DELETErequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" cu = Stripe::Customer.retrieve("cus_3tHwg1YkHpeHOJ") cu.subscriptions.retrieve("sub_3tJat5ZqB1r5I1").delete_discount()import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" cu = stripe.Customer.retrieve("cus_3tHwg1YkHpeHOJ") cu.subscriptions.retrieve("sub_3tJat5ZqB1r5I1").delete_discount()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $cu = Stripe_Customer::retrieve("cus_3tHwg1YkHpeHOJ"); $cu->subscriptions->retrieve("sub_3tJat5ZqB1r5I1")->deleteDiscount();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Customer cu = Customer.retrieve("cus_3tHwg1YkHpeHOJ"); cu.subscriptions.retrieve("sub_3tJat5ZqB1r5I1").deleteDiscount();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; stripe.customers.deleteSubscriptionDiscount("cus_3tHwg1YkHpeHOJ", "sub_3tJat5ZqB1r5I1", function(err, confirmation) { // asynchronously called }); { "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }#<Stripe::Object id=di_103Rm82eZvKYlo2CH0he3vGX 0x00000a> JSON: { "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }<Object object id=di_103Rm82eZvKYlo2CH0he3vGX at 0x00000a> JSON: { "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }{ "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }com.stripe.model.Object JSON: { "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }{ "deleted": true, "id": "di_103Rm82eZvKYlo2CH0he3vGX" }
 

Invoices

Invoices are statements of what a customer owes for a particular billing period, including subscriptions, invoice items, and any automatic proration adjustments if necessary.

Once an invoice is created, payment is automatically attempted. Note that the payment, while automatic, does not happen exactly at the time of invoice creation. If you have configured webhooks, the invoice will wait until one hour after the last webhook is successfully sent (or the last webhook times out after failing).

Any customer credit on the account is applied before determining how much is due for that invoice (the amount that will be actually charged). If the amount due for the invoice is less than 50 cents (the minimum for a charge), we add the amount to the customer's running account balance to be added to the next invoice. If this amount is negative, it will act as a credit to offset the next invoice. Note that the customer account balance does not include unpaid invoices; it only includes balances that need to be taken into account when calculating the amount due for the next invoice.

 

The invoice object

Attributes
id
string
object
string, value is "invoice"
livemode
boolean
amount_due
integer Final amount due at this time for this invoice. If the invoice’s total is smaller than the minimum charge amount, for example, or if there is account credit that can be applied to the invoice, the amount_due may be 0. If there is a positive starting_balance for the invoice (the customer owes money), the amount_due will also take that into account. The charge that gets generated for the invoice will be for the amount specified in amount_due.
attempt_count
positive integer or zero Number of automatic payment attempts made for this invoice. Does not include manual attempts to pay the invoice.
attempted
boolean Whether or not an attempt has been made to pay the invoice. An invoice is not attempted until 1 hour after the invoice.created webhook, for example, so you might not want to display that invoice as unpaid to your users.
closed
boolean Whether or not the invoice is still trying to collect payment. An invoice is closed if it’s either paid or it has been marked closed. A closed invoice will no longer attempt to collect payment.
currency
currency
customer
date
timestamp
lines
list The individual line items that make up the invoice
paid
boolean Whether or not payment was successfully collected for this invoice. An invoice can be paid (most commonly) with a charge or with credit from the customer’s account balance.
period_end
timestamp End of the usage period the invoice covers
period_start
timestamp Start of the usage period the invoice covers
starting_balance
integer Starting customer balance before attempting to pay invoice. If the invoice has not been attempted yet, this will be the current customer balance.
subtotal
integer Total of all subscriptions, invoice items, and prorations on the invoice before any discount is applied
total
integer Total after discount
application_fee
integer The fee in cents that will be applied to the invoice and transferred to the application owner’s Stripe account when the invoice is paid.
charge
description
string
discount
hash, discount object
ending_balance
integer Ending customer balance after attempting to pay invoice. If the invoice has not been attempted yet, this will be null.
next_payment_attempt
timestamp
subscription
string The subscription that this invoice was prepared for, if any.
metadata
metadata hash A set of key/value pairs that you can attach to an invoice object. It can be useful for storing additional information about the invoice in a structured format.
{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }#<Stripe::Invoice id=in_103tIt2eZvKYlo2CR77z7sig 0x00000a> JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }<Invoice invoice id=in_103tIt2eZvKYlo2CR77z7sig at 0x00000a> JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }com.stripe.model.Invoice JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }
 

The invoice_line_item object

Attributes
id
string The ID of the source of this line item, either an invoice item or a subscription
object
string line_item
livemode
boolean Whether or not this is a test line item
amount
integer The amount, in cents
currency
currency
period
hash The period this line_item covers
proration
boolean Whether or not this is a proration
type
string A string identifying the type of the source of this line item, either an invoice item or a subscription
description
string A text description of the line item, if the line item is an invoice item
metadata
metadata hash Key-value pairs attached to the line item, if the line item is an invoice item
plan
hash, plan object The plan of the subscription, if the line item is a subscription
quantity
integer The quantity of the subscription, if the line item is a subscription
{ "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }#<Stripe::Line_item id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }<Line_item line_item id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }{ "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }com.stripe.model.Line_item JSON: { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }{ "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }
 

Retrieving an Invoice

Retrieves the invoice with the given ID.

Arguments
id
required The identifier of the desired invoice.
Returns

Returns an invoice object if a valid invoice ID was provided. ReturnsRaisesRaisesThrowsThrowsThrows an error otherwise.

The invoice object contains a lines hash that contains information about the subscriptions and invoice items that have been applied to the invoice, as well as any prorations that Stripe has automatically calculated. Each line on the invoice has an amount attribute that represents the amount actually contributed to the invoice's total. For invoice items and prorations, the amount attribute is the same as for the invoice item or proration respectively. For subscriptions, the amount may be different from the plan's regular price depending on whether the invoice covers a trial period or the invoice period differs from the plan's usual interval.

The invoice object has both a subtotal and a total. The subtotal represents the total before any discounts, while the total is the final amount to be charged to the customer after all coupons have been applied.

The invoice also has a next_payment_attempt attribute that tells you the next time (as a UTC timestamp) payment for the invoice will be automatically attempted. For invoices that have been closed or that have reached the maximum number of retries (specified in your retry settings) , the next_payment_attempt will be null.

GET https://api.stripe.com/v1/invoices/{INVOICE_ID}Stripe::Invoice.retrieve({INVOICE_ID})stripe.Invoice.retrieve({INVOICE_ID})Stripe_Invoice::retrieve({INVOICE_ID});Invoice.retrieve({INVOICE_ID});stripe.invoices.retrieve({INVOICE_ID}); curl https://api.stripe.com/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Invoice::retrieve("in_103tIt2eZvKYlo2CR77z7sig");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig");var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.invoices.retrieve("in_103tIt2eZvKYlo2CR77z7sig", function(err, invoice) { // asynchronously called }); { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }
 

Retrieve an invoice's line items

When retrieving an invoice, you'll get a lines property containing the total count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Arguments
id
required The id of the invoice containing the lines to be retrieved
customer
optional In the case of upcoming invoices, the customer of the upcoming invoice is required. In other cases it is ignored.
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
subscription
optional In the case of upcoming invoices, the subscription of the upcoming invoice is optional. In other cases it is ignored.
Returns

Returns a list of line_item objects.

GET https://api.stripe.com/v1/invoices/{INVOICE_ID}/linesStripe::Invoice.retrieve({INVOICE_ID}).lines.all()stripe.Invoice.retrieve({INVOICE_ID}).lines.all()Stripe_Invoice::retrieve({INVOICE_ID})->lines->all();Invoice.retrieve({INVOICE_ID}).getLines().all();stripe.invoices.retrieveLines({INVOICE_ID}); curl https://api.stripe.com/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines?count=5&offset=5 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig").lines.all({ :count => 5, :offset => 5})import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig").lines.all( offset=5, count=5)require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Invoice::retrieve("in_103tIt2eZvKYlo2CR77z7sig")->lines->all(array( 'count'=>5, 'offset'=>5));Invoice inv = Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig"); Map lineParams = new HashMap(); lineParams.put("count", 5); lineParams.put("offset", 5); InvoiceLineItemCollection lines = inv.getLines().all(lineParams); stripe.invoices.retrieveLines( "in_103tIt2eZvKYlo2CR77z7sig", { count: 5, offset: 5 }, function(err, lines) { // asynchronously called } ); { "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines", "has_more": false, "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }, {...}, {...} ] } #<Stripe::ListObject:0x3fe634d74498> JSON: { "object": "list", "count": 3, "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines", "data": [ #<Stripe::Line_item id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }, #<Stripe::LineItem[...] ...>, #<Stripe::LineItem[...] ...> ] } { object: "list", url: "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines", has_more: false, data: [ <Line_item line_item id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }, <stripe.LineItem[...] ...>, <stripe.LineItem[...] ...> ] } Array( "object" => "list", "url" => "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines", "has_more" => false, "data" => Array( [0] => { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } [1] => <Stripe_LineItem[...] ...> [2] => <Stripe_LineItem[...] ...> ) ) #<com.stripe.model.InvoiceLineItemCollection id=#> JSON: { "data": [ com.stripe.model.Line_item JSON: { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }, #<com.stripe.model.InvoiceLineItem[...] ...>, #<com.stripe.model.InvoiceLineItem[...] ...> ], "has_more": false } { "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines", "has_more": false, "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 1999, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } }, {...}, {...} ] }
 

Creating an invoice

If you need to invoice your customer outside the regular billing cycle, you can create an invoice that pulls in all pending invoice items, including prorations. The customer's billing cycle and regular subscription won't be affected.

Once you create the invoice, it'll be picked up and paid automatically, though you can choose to pay it right away.

Arguments
customer
required
application_fee
optional A fee in cents that will be applied to the invoice and transferred to the application owner’s Stripe account. The request must be made with an OAuth key in order to take an application fee. For more information, see the application fees documentation.
description
optional
metadata
optional
subscription
optional The ID of the subscription to invoice. If not set, the created invoice will include all pending invoice items for the customer. If set, the created invoice will exclude pending invoice items that pertain to a subscription other than the specified subscription.
Returns

Returns the invoice object if there are pending invoice items to invoice.

ReturnsRaisesRaisesThrowsThrowsThrows an error if there are no pending invoice items or if the customer ID provided is invalid.

POST https://api.stripe.com/v1/invoicesStripe::Invoice.create() stripe.Invoice.create() Stripe_Invoice::create(); Invoice.create(); stripe.invoices.create(); curl https://api.stripe.com/v1/invoices \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d customer=cus_3tHwg1YkHpeHOJrequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Invoice.create( :customer => "cus_3tHwg1YkHpeHOJ" )import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Invoice.create( customer="cus_3tHwg1YkHpeHOJ"require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Invoice::create(array( "customer" => "cus_3tHwg1YkHpeHOJ" ));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> invoiceParams = new HashMap<String, Object>(); invoiceParams.put("customer", "cus_3tHwg1YkHpeHOJ"); Invoice.create(invoiceParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.invoices.create({ customer: "cus_3tHwg1YkHpeHOJ" }, function(err, invoice) { // asynchronously called }); { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }#<Stripe::Invoice id=in_103tIt2eZvKYlo2CR77z7sig 0x00000a> JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }<Invoice invoice id=in_103tIt2eZvKYlo2CR77z7sig at 0x00000a> JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }com.stripe.model.Invoice JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }
 

Paying an invoice

Stripe automatically creates and then attempts to pay invoices for customers on subscriptions. We'll also retry unpaid invoices according to your retry settings. However, if you'd like to attempt to collect payment on an invoice out of the normal retry schedule or for some other reason, you can do so.

Arguments
id
required
Returns

Returns the invoice object.

POST https://api.stripe.com/v1/invoices/{INVOICE_ID}/payinvoice = Stripe::Invoice.retrieve({INVOICE_ID}) invoice.pay invoice = stripe.Invoice.retrieve({INVOICE_ID}) invoice.pay() $invoice = Stripe_Invoice::retrieve({INVOICE_ID}); $invoice->pay(); invoice = Invoice.retrieve({INVOICE_ID}); invoice.pay(); stripe.invoices.pay({INVOICE_ID}); curl https://api.stripe.com/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/pay \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X POSTrequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" invoice = Stripe::Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig") invoice.payimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" invoice = stripe.Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig") invoice.pay()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $invoice = Stripe_Invoice::retrieve("in_103tIt2eZvKYlo2CR77z7sig"); $invoice->pay();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; invoice = Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig"); invoice.pay();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; stripe.invoices.pay("in_103tIt2eZvKYlo2CR77z7sig", function(err, invoice) { // asynchronously called }); { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": true, "closed": false, "paid": true, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null, "last_payment_attempt": null }#<Stripe::Invoice id=in_103tIt2eZvKYlo2CR77z7sig 0x00000a> JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": true, "closed": false, "paid": true, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null, "last_payment_attempt": null }<Invoice invoice id=in_103tIt2eZvKYlo2CR77z7sig at 0x00000a> JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": true, "closed": false, "paid": true, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null, "last_payment_attempt": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": true, "closed": false, "paid": true, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null, "last_payment_attempt": null }com.stripe.model.Invoice JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": true, "closed": false, "paid": true, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null, "last_payment_attempt": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "ii_103n902eZvKYlo2CfQmZCSQD", "object": "line_item", "type": "invoiceitem", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1396623292, "end": 1396623292 }, "quantity": null, "plan": null, "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { } } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": true, "closed": false, "paid": true, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null, "last_payment_attempt": null }
 

Updating an invoice

Until an invoice is paid, it is marked as open (closed=false). If you'd like to stop Stripe from automatically attempting payment on an invoice or would simply like to close the invoice out as no longer owed by the customer, you can update the closed parameter.

Arguments
application_fee
optional A fee in cents that will be applied to the invoice and transferred to the application owner’s Stripe account. The request must be made with an OAuth key in order to take an application fee. For more information, see the application fees documentation.
closed
optional Boolean representing whether an invoice is closed or not. To close an invoice, pass true.
description
optional
metadata
optional
Returns

Returns the invoice object.

POST https://api.stripe.com/v1/invoices/{INVOICE_ID}invoice = Stripe::Invoice.retrieve({INVOICE_ID}) invoice.closed = true ... invoice.save invoice = stripe.Invoice.retrieve({INVOICE_ID}) invoice.closed = True ... invoice.save() $invoice = Stripe_Invoice::retrieve({INVOICE_ID}); $invoice->closed = true; ... $invoice->save(); Invoice invoice = Invoice.retrieve({INVOICE_ID}); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("closed", "true"); ... invoice.update(updateParams);stripe.invoices.retrieve({INVOICE_ID}, { closed: true, ... }); curl https://api.stripe.com/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d closed=truerequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" invoice = Stripe::Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig") invoice.saveimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" invoice = stripe.Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig") invoice.closed = True invoice.save()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $invoice = Stripe_Invoice::retrieve("in_103tIt2eZvKYlo2CR77z7sig"); $invoice->closed = true $invoice->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Invoice invoice = Invoice.retrieve("in_103tIt2eZvKYlo2CR77z7sig"); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("closed", "true"); invoice.update(updateParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.invoices.update( "in_103tIt2eZvKYlo2CR77z7sig", { closed: true }, function(err, invoice) { // asynchronously called } ) { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": true, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }#<Stripe::Invoice id=in_103tIt2eZvKYlo2CR77z7sig 0x00000a> JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": true, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }<Invoice invoice id=in_103tIt2eZvKYlo2CR77z7sig at 0x00000a> JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": true, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": true, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }com.stripe.model.Invoice JSON: { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": true, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": true, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }
 

Retrieving a List of Invoices

You can list all invoices, or list the invoices for a specific customer. The invoices are returned sorted by creation date, with the most recently created invoices appearing first.

Arguments
customer
optional The identifier of the customer whose invoices to return. If none is provided, all invoices will be returned.
date
optional A filter on the list based on the object date field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
Returns

A dictionaryhashdictionaryassociative arrayMapobject with a data property that contains an array of invoice objects. ReturnsRaisesRaisesThrowsThrowsThrows an error if the customer ID is invalid.

GET https://api.stripe.com/v1/invoicesStripe::Invoice.allstripe.Invoice.all()Stripe_Invoice::all();Invoice.all(Map options);stripe.invoices.list(); curl https://api.stripe.com/v1/invoices?customer=cus_3tHwg1YkHpeHOJ \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Invoice.all( :customer => "cus_3tHwg1YkHpeHOJ", :count => 3 )import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Invoice.all( customer="cus_3tHwg1YkHpeHOJ", count=3)require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Invoice::all(array( "customer" => "cus_3tHwg1YkHpeHOJ", "count" => 3) );Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> invoiceParams = new HashMap<String, Object>(); invoiceParams.put("customer", "cus_3tHwg1YkHpeHOJ"); invoiceParams.put("count", 3); Invoice.all(invoiceParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.invoices.list( { customer: "cus_3tHwg1YkHpeHOJ", count: 3 }, function(err, invoices) { // asynchronously called } ); { "object": "list", "url": "/v1/invoices", "has_more": false, "data": [ { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }, {...}, {...} ] } #<Stripe::ListObject:0x3fe634d74498> JSON: { "object": "list", "count": 3, "url": "/v1/invoices", "data": [ { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }, #<Stripe::Invoice[...] ...>, #<Stripe::Invoice[...] ...> ] } { object: "list", url: "/v1/invoices", has_more: false, data: [ { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }, <stripe.Invoice[...] ...>, <stripe.Invoice[...] ...> ] } Array( "object" => "list", "url" => "/v1/invoices", "has_more" => false, "data" => Array( [0] => { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null } [1] => <Stripe_Invoice[...] ...> [2] => <Stripe_Invoice[...] ...> ) ) #<com.stripe.model.InvoiceCollection id=#> JSON: { "data": [ { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }, #<com.stripe.model.Invoice[...] ...>, #<com.stripe.model.Invoice[...] ...> ], "has_more": false } { "object": "list", "url": "/v1/invoices", "has_more": false, "data": [ { "date": 1398043925, "id": "in_103tIt2eZvKYlo2CR77z7sig", "period_start": 1395365367, "period_end": 1398043767, "lines": { "data": [ { "id": "sub_3tJat5ZqB1r5I1", "object": "line_item", "type": "subscription", "livemode": true, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1400638478, "end": 1403316878 }, "quantity": 1, "plan": { "interval": "month", "name": "New plan name", "created": 1386247539, "amount": 2000, "currency": "usd", "id": "gold21323", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { }, "statement_description": null }, "description": null, "metadata": null } ], "count": 1, "object": "list", "url": "/v1/invoices/in_103tIt2eZvKYlo2CR77z7sig/lines" }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }, {...}, {...} ] }
 

Retrieving a Customer's Upcoming Invoice

At any time, you can view the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discount that is applicable to the customer.

Arguments
customer
required The identifier of the customer whose upcoming invoice you'd like to retrieve.
subscription
optional The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, you will retrieve the next upcoming invoice from among the customer's subscriptions.
Returns

Returns an invoice if a valid customer ID was provided. ReturnsRaisesRaisesThrowsThrowsThrows an error otherwise.

GET https://api.stripe.com/v1/invoices/upcomingStripe::Invoice.upcoming(:customer => {CUSTOMER_ID}) stripe.Invoice.upcoming(customer={CUSTOMER_ID}) Stripe_Invoice::upcoming(array("customer" => {CUSTOMER_ID})); Map<String, Object> invoiceParams = new HashMap<String, Object>(); invoiceParams.put("customer", {CUSTOMER_ID}); Invoice.upcoming(invoiceParams);stripe.invoices.retrieveUpcoming({CUSTOMER_ID}) curl https://api.stripe.com/v1/invoices/upcoming?customer=cus_3tHwg1YkHpeHOJ \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Invoice.upcoming(:customer => "cus_3tHwg1YkHpeHOJ")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Invoice.upcoming(customer="cus_3tHwg1YkHpeHOJ")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Invoice::upcoming(array("customer" => "cus_3tHwg1YkHpeHOJ"));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> invoiceParams = new HashMap<String, Object>(); invoiceParams.put("customer", "cus_3tHwg1YkHpeHOJ"); Invoice.upcoming(invoiceParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.invoices.retrieveUpcoming( "cus_3tHwg1YkHpeHOJ", function(err, upcoming) { // asynchronously called } ); { "date": 1398043925, "period_start": 1395365367, "period_end": 1398043767, "lines": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/invoices/upcoming/lines?customer=cus_3tHwg1YkHpeHOJ", "data": [ { "id": "sub_3hgrp1pIrupHVw", "object": "line_item", "type": "subscription", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1398043767, "end": 1400635767 }, "quantity": 1, "plan": { "interval": "month", "name": "test", "created": 1391369777, "amount": 2000, "currency": "usd", "id": "test", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { "storage": "100000000", "speed": "1024" }, "statement_description": null }, "description": null, "metadata": null } ] }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }#<Stripe::Invoice 0x00000a> JSON: { "date": 1398043925, "period_start": 1395365367, "period_end": 1398043767, "lines": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/invoices/upcoming/lines?customer=cus_3tHwg1YkHpeHOJ", "data": [ { "id": "sub_3hgrp1pIrupHVw", "object": "line_item", "type": "subscription", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1398043767, "end": 1400635767 }, "quantity": 1, "plan": { "interval": "month", "name": "test", "created": 1391369777, "amount": 2000, "currency": "usd", "id": "test", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { "storage": "100000000", "speed": "1024" }, "statement_description": null }, "description": null, "metadata": null } ] }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }<Invoice invoice at 0x00000a> JSON: { "date": 1398043925, "period_start": 1395365367, "period_end": 1398043767, "lines": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/invoices/upcoming/lines?customer=cus_3tHwg1YkHpeHOJ", "data": [ { "id": "sub_3hgrp1pIrupHVw", "object": "line_item", "type": "subscription", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1398043767, "end": 1400635767 }, "quantity": 1, "plan": { "interval": "month", "name": "test", "created": 1391369777, "amount": 2000, "currency": "usd", "id": "test", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { "storage": "100000000", "speed": "1024" }, "statement_description": null }, "description": null, "metadata": null } ] }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "period_start": 1395365367, "period_end": 1398043767, "lines": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/invoices/upcoming/lines?customer=cus_3tHwg1YkHpeHOJ", "data": [ { "id": "sub_3hgrp1pIrupHVw", "object": "line_item", "type": "subscription", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1398043767, "end": 1400635767 }, "quantity": 1, "plan": { "interval": "month", "name": "test", "created": 1391369777, "amount": 2000, "currency": "usd", "id": "test", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { "storage": "100000000", "speed": "1024" }, "statement_description": null }, "description": null, "metadata": null } ] }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }com.stripe.model.Invoice JSON: { "date": 1398043925, "period_start": 1395365367, "period_end": 1398043767, "lines": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/invoices/upcoming/lines?customer=cus_3tHwg1YkHpeHOJ", "data": [ { "id": "sub_3hgrp1pIrupHVw", "object": "line_item", "type": "subscription", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1398043767, "end": 1400635767 }, "quantity": 1, "plan": { "interval": "month", "name": "test", "created": 1391369777, "amount": 2000, "currency": "usd", "id": "test", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { "storage": "100000000", "speed": "1024" }, "statement_description": null }, "description": null, "metadata": null } ] }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }{ "date": 1398043925, "period_start": 1395365367, "period_end": 1398043767, "lines": { "object": "list", "total_count": 1, "has_more": false, "url": "/v1/invoices/upcoming/lines?customer=cus_3tHwg1YkHpeHOJ", "data": [ { "id": "sub_3hgrp1pIrupHVw", "object": "line_item", "type": "subscription", "livemode": false, "amount": 2000, "currency": "usd", "proration": false, "period": { "start": 1398043767, "end": 1400635767 }, "quantity": 1, "plan": { "interval": "month", "name": "test", "created": 1391369777, "amount": 2000, "currency": "usd", "id": "test", "object": "plan", "livemode": false, "interval_count": 1, "trial_period_days": null, "metadata": { "storage": "100000000", "speed": "1024" }, "statement_description": null }, "description": null, "metadata": null } ] }, "subtotal": 2000, "total": 2000, "customer": "cus_3tHwg1YkHpeHOJ", "object": "invoice", "attempted": false, "closed": false, "paid": false, "livemode": false, "attempt_count": 0, "amount_due": 2000, "currency": "usd", "starting_balance": 0, "ending_balance": null, "next_payment_attempt": 1398047525, "charge": null, "discount": null, "application_fee": null, "subscription": "sub_3hgrp1pIrupHVw", "metadata": { }, "description": null }
 

Invoice items

Sometimes 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.

 

The invoiceitem object

Attributes
id
string
object
string, value is "invoiceitem"
livemode
boolean
amount
integer
currency
currency
customer
date
timestamp
proration
boolean Whether or not the invoice item was created automatically as a proration adjustment when the customer switched plans
description
string
invoice
metadata
metadata hash A set of key/value pairs that you can attach to an invoice item object. It can be useful for storing additional information about the invoice item in a structured format.
subscription
string The subscription that this invoice item has been created for, if any.
{ "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }#<Stripe::InvoiceItem id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }<InvoiceItem invoiceitem id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }{ "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }com.stripe.model.InvoiceItem JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }{ "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }
 

Creating an Invoice Item

Adds an arbitrary charge or credit to the customer's upcoming invoice.

Arguments
customer
required The ID of the customer who will be billed when this invoice item is billed.
amount
required The integer amount in cents of the charge to be applied to the upcoming invoice. If you want to apply a credit to the customer's account, pass a negative amount.
currency
required 3-letter ISO code for currency.
invoice
optional The ID of an existing invoice to add this invoice item to. When left blank, the invoice item will be added to the next upcoming scheduled invoice. Use this when adding invoice items in response to an invoice.created webhook. You cannot add an invoice item to an invoice that has already been paid or closed.
subscription
optional The ID of a subscription to add this invoice item to. When left blank, the invoice item will be be added to the next upcoming scheduled invoice. When set, scheduled invoices for subscriptions other than the specified subscription will ignore the invoice item. Use this when you want to express that an invoice item has been accrued within the context of a particular subscription.
description
optional, default is nullnilNonenullnullnull An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking.
metadata
optional, default is { }{ }{ }{ }{ }{ } A set of key/value pairs that you can attach to an invoice item object. It can be useful for storing additional information about the invoice item in a structured format.
Returns

The created invoice item object is returned if successful. Otherwise, this call returnsraisesraisesthrowsthrowsthrows an error.

POST https://api.stripe.com/v1/invoiceitemsStripe::InvoiceItem.create() stripe.InvoiceItem.create() Stripe_InvoiceItem::create(); InvoiceItem.create(); stripe.invoiceItems.create(); curl https://api.stripe.com/v1/invoiceitems \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d customer=cus_3tHwg1YkHpeHOJ \ -d amount=1000 \ -d currency=usd \ -d "description=One-time setup fee"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::InvoiceItem.create( :customer => "cus_3tHwg1YkHpeHOJ", :amount => 1000, :currency => "usd", :description => "One-time setup fee" )import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.InvoiceItem.create( customer="cus_3tHwg1YkHpeHOJ", amount=1000, currency="usd", description="One-time setup fee")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_InvoiceItem::create(array( "customer" => "cus_3tHwg1YkHpeHOJ", "amount" => 1000, "currency" => "usd", "description" => "One-time setup fee") );Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> invoiceItemParams = new HashMap<String, Object>(); invoiceItemParams.put("customer", "cus_3tHwg1YkHpeHOJ"); invoiceItemParams.put("amount", 1000); invoiceItemParams.put("currency", "usd"); invoiceItemParams.put("description", "One-time setup fee"); InvoiceItem.create(invoiceItemParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.invoiceItems.create({ customer: "cus_3tHwg1YkHpeHOJ", amount: 1000, currency: "usd", description: "One-time setup fee" }, function(err, invoiceItem) { // asynchronously called }); { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }#<Stripe::InvoiceItem id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }<InvoiceItem invoiceitem id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }{ "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }com.stripe.model.InvoiceItem JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }{ "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }
 

Retrieving an Invoice Item

Retrieves the invoice item with the given ID.

Arguments
id
required The ID of the desired invoice item.
Returns

Returns an invoice item if a valid invoice item ID was provided. ReturnsRaisesRaisesThrowsThrowsThrows an error otherwise.

GET https://api.stripe.com/v1/invoiceitems/{ID}Stripe::InvoiceItem.retrieve({ID}) stripe.InvoiceItem.retrieve({ID}) Stripe_InvoiceItem::retrieve({ID}); InvoiceItem.retrieve({ID}); stripe.invoiceItems.retrieve({ID}); curl https://api.stripe.com/v1/invoiceitems/ii_103n902eZvKYlo2CfQmZCSQD \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_InvoiceItem::retrieve("ii_103n902eZvKYlo2CfQmZCSQD");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD");var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.invoiceItems.retrieve("ii_103n902eZvKYlo2CfQmZCSQD", function(err, invoiceItem) { // asynchronously called }); { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }#<Stripe::InvoiceItem id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }<InvoiceItem invoiceitem id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }{ "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }com.stripe.model.InvoiceItem JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }{ "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }
 

Updating an Invoice Item

Updates the amount or description of an invoice item on an upcoming invoice. Updating an invoice item is only possible before the invoice it's attached to is closed.

Arguments
amount
optional The integer amount in cents of the charge to be applied to the upcoming invoice. If you want to apply a credit to the customer's account, pass a negative amount.
description
optional An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
metadata
optional, default is { }{ }{ }{ }{ }{ } A set of key/value pairs that you can attach to an invoice item object. It can be useful for storing additional information about the invoice item in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to nullnilNonenullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnull, then save.
Returns

The updated invoice item object is returned upon success. Otherwise, this call returnsraisesraisesthrowsthrowsthrows an error.

POST https://api.stripe.com/v1/invoiceitems/{INVOICEITEM_ID}ii = Stripe::InvoiceItem.retrieve({INVOICEITEM_ID}) ii.amount = {AMOUNT} ... ii.save ii = stripe.InvoiceItem.retrieve({INVOICEITEM_ID}) ii.amount = {AMOUNT} ... ii.save() $ii = Stripe_InvoiceItem::retrieve({INVOICEITEM_ID}); $ii->amount = {AMOUNT}; ... $ii->save(); InvoiceItem ii = InvoiceItem.retrieve({INVOICEITEM_ID}); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("amount", {AMOUNT}); ... ii.update(updateParams);stripe.invoiceItems.update({INVOICEITEM_ID}, { amount: {AMOUNT} }) curl https://api.stripe.com/v1/invoiceitems/ii_103n902eZvKYlo2CfQmZCSQD \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d amount=1500 \ -d "description=Customer for test@example.com"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ii = Stripe::InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD") ii.amount = 1500 ii.description = "Customer for test@example.com" ii.saveimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ii = stripe.InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD") ii.amount = 1500 ii.description = "Customer for test@example.com" ii.save()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $ii = Stripe_InvoiceItem::retrieve("ii_103n902eZvKYlo2CfQmZCSQD"); $ii->amount = 1500; $ii->description = "Customer for test@example.com"; $ii->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; InvoiceItem ii = InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD"); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("amount", 1500); updateParams.put("description", "Customer for test@example.com"); ii.update(updateParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.invoiceItems.update( "ii_103n902eZvKYlo2CfQmZCSQD", { amount: 1500, description: "Customer for test@example.com" }, function(err, invoiceItem) { // asynchronously called } ); { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 1500, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Customer for test@example.com", "metadata": { }, "invoice": null, "subscription": null }#<Stripe::InvoiceItem id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 1500, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Customer for test@example.com", "metadata": { }, "invoice": null, "subscription": null }<InvoiceItem invoiceitem id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 1500, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Customer for test@example.com", "metadata": { }, "invoice": null, "subscription": null }{ "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 1500, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Customer for test@example.com", "metadata": { }, "invoice": null, "subscription": null }com.stripe.model.InvoiceItem JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 1500, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Customer for test@example.com", "metadata": { }, "invoice": null, "subscription": null }{ "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 1500, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Customer for test@example.com", "metadata": { }, "invoice": null, "subscription": null }
 

Deleting an Invoice Item

Removes an invoice item from the upcoming invoice. Removing an invoice item is only possible before the invoice it's attached to is closed.

Arguments
id
required The identifier of the invoice item to be deleted.
Returns

An object with the deleted invoice item's ID and a deleted flag upon success. This call returnsraisesraisesthrowsthrowsthrows an error otherwise, such as when the invoice item has already been deleted.

DELETE https://api.stripe.com/v1/invoiceitems/{INVOICEITEM_ID}ii = Stripe::InvoiceItem.retrieve({INVOICEITEM_ID}) ii.delete ii = stripe.InvoiceItem.retrieve({INVOICEITEM_ID}) ii.delete() $ii = Stripe_InvoiceItem::retrieve({INVOICEITEM_ID}); $ii->delete(); InvoiceItem ii = InvoiceItem.retrieve({INVOICEITEM_ID}); ii.delete(); stripe.invoiceItems.del({INVOICEITEM_ID}); curl https://api.stripe.com/v1/invoiceitems/ii_103n902eZvKYlo2CfQmZCSQD \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X DELETErequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ii = Stripe::InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD") ii.deleteimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ii = stripe.InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD") ii.delete()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $ii = Stripe_InvoiceItem::retrieve("ii_103n902eZvKYlo2CfQmZCSQD"); $ii->delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; InvoiceItem ii = InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD"); ii.delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; stripe.invoiceItems.del("ii_103n902eZvKYlo2CfQmZCSQD", function(err, confirmation) { // asynchronously called }); { "deleted": true, "id": "ii_103n902eZvKYlo2CfQmZCSQD" }#<Stripe::Object id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: { "deleted": true, "id": "ii_103n902eZvKYlo2CfQmZCSQD" }<Object object id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: { "deleted": true, "id": "ii_103n902eZvKYlo2CfQmZCSQD" }{ "deleted": true, "id": "ii_103n902eZvKYlo2CfQmZCSQD" }com.stripe.model.Object JSON: { "deleted": true, "id": "ii_103n902eZvKYlo2CfQmZCSQD" }{ "deleted": true, "id": "ii_103n902eZvKYlo2CfQmZCSQD" }
 

List all Invoice Items

Returns a list of your invoice items. Invoice Items are returned sorted by creation date, with the most recently created invoice items appearing first.

Arguments
created
optional A filter on the list based on the object created field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:
customer
optional The identifier of the customer whose invoice items to return. If none is provided, all invoice items will be returned.
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
Returns

A dictionaryhashdictionaryassociative arrayMapobject with a data property that contains an array of up to limit invoice items, starting after invoice item starting_after. Each entry in the array is a separate invoice item object. If no more invoice items are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrow an error.

You can optionally request that the response include the total count of all invoice items that match your filters. To do so, specify `include[]=total_count` in your request.

GET https://api.stripe.com/v1/invoiceitemsStripe::InvoiceItem.allstripe.InvoiceItem.all()Stripe_InvoiceItem->all();InvoiceItem.all(Map options);stripe.invoiceItems.list(); curl https://api.stripe.com/v1/invoiceitems \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::InvoiceItem.allimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.InvoiceItem.all()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_InvoiceItem::all();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; InvoiceItem.all(new HashMap<String, Object>());var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.invoiceItems.list(function(err, invoiceItems) { // asynchronously called }); { "object": "list", "url": "/v1/invoiceitems", "has_more": false, "data": [ { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }, {...}, {...} ] } #<Stripe::ListObject:0x3fe634d74498> JSON: { "object": "list", "count": 3, "url": "/v1/invoiceitems", "data": [ #<Stripe::InvoiceItem id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }, #<Stripe::InvoiceItem[...] ...>, #<Stripe::InvoiceItem[...] ...> ] } { object: "list", url: "/v1/invoiceitems", has_more: false, data: [ <InvoiceItem invoiceitem id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }, <stripe.InvoiceItem[...] ...>, <stripe.InvoiceItem[...] ...> ] } Array( "object" => "list", "url" => "/v1/invoiceitems", "has_more" => false, "data" => Array( [0] => { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null } [1] => <Stripe_InvoiceItem[...] ...> [2] => <Stripe_InvoiceItem[...] ...> ) ) #<com.stripe.model.InvoiceItemCollection id=#> JSON: { "data": [ com.stripe.model.InvoiceItem JSON: { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }, #<com.stripe.model.InvoiceItem[...] ...>, #<com.stripe.model.InvoiceItem[...] ...> ], "has_more": false } { "object": "list", "url": "/v1/invoiceitems", "has_more": false, "data": [ { "object": "invoiceitem", "id": "ii_103n902eZvKYlo2CfQmZCSQD", "date": 1396623292, "amount": 2000, "livemode": false, "proration": false, "currency": "usd", "customer": "cus_3tHwg1YkHpeHOJ", "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296", "metadata": { }, "invoice": null, "subscription": null }, {...}, {...} ] }
 

Disputes

A 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.

 

The dispute object

Attributes
object
string, value is "dispute"
livemode
boolean
amount
integer Disputed amount. Usually the amount of the charge, but can differ (usually because of currency fluctuation or because only part of the order is disputed).
charge
created
timestamp Date dispute was opened
currency
currency Three-letter ISO currency code representing the currency in which the disputed charge was made.
reason
string Reason given by cardholder for dispute. Possible values are duplicate, fraudulent, subscription_canceled, product_unacceptable, product_not_received, unrecognized, credit_not_processed, general. Read more about dispute reasons.
status
string Current status of dispute. Possible values are won, lost, needs_response, under_review.
balance_transaction
evidence
string Evidence that you have submitted to demonstrate the charge is legitimate (proof of delivery, IP addresses of logins, text of invoices, etc.). There is a limit of 300,000 characters.
evidence_due_by
timestamp Date by which evidence must be submitted in order to successfully challenge dispute. Will be null if the customer’s bank or credit card company doesn’t allow a response for this particular dispute.
is_protected
boolean
{ "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }#<Stripe::Dispute 0x00000a> JSON: { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }<Dispute dispute at 0x00000a> JSON: { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }{ "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }com.stripe.model.Dispute JSON: { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }{ "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }
 

Updating a dispute

Contacting your customer is always the best first step, but if that doesn't work, you can submit (text-only) evidence in order to help us resolve the dispute in your favor. You can do this in your dashboard, but if you prefer, you can use the API to submit evidence programmatically.

Arguments
evidence
optional
Returns

Returns the dispute object.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/disputecharge = Stripe::Charge.retrieve({CHARGE_ID}) charge.update_dispute(:evidence => {NEW_EVIDENCE}) charge = stripe.Charge.retrieve({CHARGE_ID}) charge.update_dispute(evidence={NEW_EVIDENCE}) $charge = Stripe_Charge::retrieve({CHARGE_ID}); $charge.updateDispute(array("evidence" => {NEW_EVIDENCE})); Charge ch = Charge.retrieve({CHARGE_ID}); Map disputeParams = new HashMap(); disputeParams.put("evidence", {NEW_EVIDENCE}); ch.updateDispute(disputeParams); stripe.charges.updateDispute({CHARGE_ID}, { evidence: {NEW_EVIDENCE} }); curl https://api.stripe.com/v1/charges/ch_103tJZ2eZvKYlo2CSyNNLbLP/dispute \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d "evidence=Here's evidence showing this charge is legitimate."require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" charge = Stripe::Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP") charge.update_dispute(:evidence => "Here's evidence showing this charge is legitimate.")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" charge = stripe.Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP") charge.update_dispute(evidence="Here's evidence showing this charge is legitimate.") charge.save()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $ch = Stripe_Charge::retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP"); $ch->updateDispute(array("evidence" => "Here's evidence showing this charge is legitimate."));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Charge ch = Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP"); Map<String, Object> params = new HashMap<String, Object>(); params.put("evidence", "Here's evidence showing this charge is legitimate."); ch.updateDispute(params)var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.charges.updateDispute( "ch_103tJZ2eZvKYlo2CSyNNLbLP", {evidence: "Here's evidence showing this charge is legitimate."}, function(err, dispute) { // asynchronously called } ); { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": "Here's evidence showing this charge is legitimate." }#<Stripe::Dispute 0x00000a> JSON: { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": "Here's evidence showing this charge is legitimate." }<Dispute dispute at 0x00000a> JSON: { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": "Here's evidence showing this charge is legitimate." }{ "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": "Here's evidence showing this charge is legitimate." }com.stripe.model.Dispute JSON: { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": "Here's evidence showing this charge is legitimate." }{ "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "needs_response", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": "Here's evidence showing this charge is legitimate." }
 

Closing a dispute

Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially 'dismissing' the dispute, acknowledging it as lost.

The status of the dispute will change from under_review to lost. Closing a dispute is irreversible.

Arguments
id
required
Returns

Returns the dispute object.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/dispute/closecharge = Stripe::Charge.retrieve({CHARGE_ID}) charge.close_dispute charge = stripe.Charge.retrieve({CHARGE_ID}) charge.close_dispute() $charge = Stripe_Charge::retrieve({CHARGE_ID}); $charge.closeDispute(); Charge ch = Charge.retrieve({CHARGE_ID}); ch.closeDispute(); stripe.charges.closeDispute({CHARGE_ID}); curl https://api.stripe.com/v1/charges/ch_103tJZ2eZvKYlo2CSyNNLbLP/dispute/close \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X POSTrequire "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" charge = Stripe::Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP") charge.close_disputeimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" charge = stripe.Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP") charge.close_dispute()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $ch = Stripe_Charge::retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP"); $ch->closeDispute();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Charge ch = Charge.retrieve("ch_103tJZ2eZvKYlo2CSyNNLbLP"); ch.closeDispute()var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.charges.closeDispute( "ch_103tJZ2eZvKYlo2CSyNNLbLP", function(err, charge) { // asynchronously called } ); { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "lost", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }#<Stripe::Dispute 0x00000a> JSON: { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "lost", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }<Dispute dispute at 0x00000a> JSON: { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "lost", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }{ "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "lost", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }com.stripe.model.Dispute JSON: { "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "lost", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }{ "charge": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "amount": 1000, "created": 1398046478, "status": "lost", "livemode": false, "currency": "usd", "object": "dispute", "reason": "general", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "evidence_due_by": 1399766399, "evidence": null }
 

Transfers

When Stripe sends you money or you initiate a transfer to a third party bank account, a transfer object will be created. You can retrieve individual transfers as well as list all transfers.

Currently, only US accounts can create transfers.

View the documentation on creating transfers via the API.

 

The transfer object

Attributes
id
string
object
string, value is "transfer"
livemode
boolean
amount
integer Amount (in cents) to be transferred to your bank account
created
timestamp Time that this record of the transfer was first created.
currency
currency
date
timestamp Date the transfer was initiated. If the transfer is pending, the date the transfer is scheduled to go out.
status
string Current status of the transfer (paid, pending, or failed). A transfer will be pending until it is submitted, at which point it becomes paid. If it does not go through successfully, its status will change to failed.
account
hash or null Hash describing the account this transfer was sent to
balance_transaction
description
string Internal-only description of the transfer
metadata
metadata hash A set of key/value pairs that you can attach to a transfer object. It can be useful for storing additional information about the transfer in a structured format.
recipient
string ID of the recipient this transfer is for if one exists. Transfers to your bank account do not have a recipient.
statement_description
string Extra information about a transfer to be displayed on the user’s bank statement.
{ "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }#<Stripe::Transfer id=tr_103tJD2eZvKYlo2CbDua7SMQ 0x00000a> JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }<Transfer transfer id=tr_103tJD2eZvKYlo2CbDua7SMQ at 0x00000a> JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }{ "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }com.stripe.model.Transfer JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }{ "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }
 

Creating a new transfer (sending funds to a third-party bank account)

To send funds from your Stripe account to a third-party bank account, you create a new transfer object. Your Stripe balance must be able to cover the transfer amount, or you'll receive an "Insufficient Funds" error.

If your API key is in test mode, money won't actually be sent, though everything else will occur as if in live mode.

Arguments
amount
required A positive integer in cents representing how much to transfer.
currency
required 3-letter ISO code for currency.
recipient
required The ID of an existing, verified recipient that the money will be transferred to in this request. If self, the money will be transferred to the bank account associated with your account.
description
optional, default is nullnilNonenullnullnull An arbitrary string which you can attach to a transfer object. It is displayed when in the web interface alongside the transfer.
statement_description
optional, default is nullnilNonenullnullnull An arbitrary string which will be displayed on the recipient's bank statement. This should not include your company name, as that will already be part of the descriptor. The maximum length of this string is 15 characters; longer strings will be truncated. For example, if your website is EXAMPLE.COM and you pass in INVOICE 1234, the user will see EXAMPLE.COM INVOICE 1234. Note: While most banks display this information consistently, some may display it incorrectly or not at all.
metadata
optional, default is { } A set of key/value pairs that you can attach to a transfer object. It can be useful for storing additional information about the transfer in a structured format.
Returns

Returns a transfer object if there were no initial errors with the transfer creation (invalid routing number, insufficient funds, etc). The status of the transfer object will be initially marked as pending.

POST https://api.stripe.com/v1/transfersStripe::Transfer.createstripe.Transfer.create()Stripe_Transfer::create();Transfer.create();stripe.transfers.create(); curl https://api.stripe.com/v1/transfers \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d amount=400 \ -d currency=usd \ -d recipient=rp_103sX72eZvKYlo2CYsowgwLq \ -d "description=Transfer to test@example.com"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Transfer.create( :amount => 400, :currency => "usd", :recipient => "rp_103sX72eZvKYlo2CYsowgwLq", :description => "Transfer for test@example.com" )import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Transfer.create( amount=400, currency="usd", recipient="rp_103sX72eZvKYlo2CYsowgwLq", description="Transfer for test@example.com" )require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Transfer::create(array( "amount" => 400, "currency" => "usd", "recipient" => "rp_103sX72eZvKYlo2CYsowgwLq", "description" => "Transfer for test@example.com" ));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> transferParams = new HashMap<String, Object>(); transferParams.put("amount", 400); transferParams.put("currency", "usd"); transferParams.put("recipient", "rp_103sX72eZvKYlo2CYsowgwLq"); transferParams.put("description", "Transfer for test@example.com"); Transfer.create(transferParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.transfers.create({ amount: 400, currency: "usd", recipient: "rp_103sX72eZvKYlo2CYsowgwLq", description: "Transfer for test@example.com" }, function(err, transfer) { // asynchronously called }); { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }#<Stripe::Transfer id=tr_103tJD2eZvKYlo2CbDua7SMQ 0x00000a> JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }<Transfer transfer id=tr_103tJD2eZvKYlo2CbDua7SMQ at 0x00000a> JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }{ "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }com.stripe.model.Transfer JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }{ "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }
 

Retrieving a Transfer

Retrieves the details of an existing transfer. Supply the unique transfer ID from either a transfer creation request or the transfer list, and Stripe will return the corresponding transfer information.

Arguments
id
required The identifier of the transfer to be retrieved.
Returns

Returns a transfer object if a valid identifier was provided, and returnsraisesraisesthrowsthrowsthrows an error otherwise.

GET https://api.stripe.com/v1/transfers/{TRANSFER_ID}Stripe::Transfer.retrieve({TRANSFER_ID})stripe.Transfer.retrieve({TRANSFER_ID})Stripe_Transfer::retrieve({TRANSFER_ID});Transfer.retrieve({TRANSFER_ID});stripe.transfers.retrieve({TRANSFER_ID}); curl https://api.stripe.com/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Transfer.retrieve("tr_103tJD2eZvKYlo2CbDua7SMQ")import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Transfer.retrieve("tr_103tJD2eZvKYlo2CbDua7SMQ")require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Transfer::retrieve("tr_103tJD2eZvKYlo2CbDua7SMQ");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Transfer.retrieve("tr_103tJD2eZvKYlo2CbDua7SMQ");var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.transfers.retrieve("tr_103tJD2eZvKYlo2CbDua7SMQ", function(err, transfer) { // asynchronously called }); { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }#<Stripe::Transfer id=tr_103tJD2eZvKYlo2CbDua7SMQ 0x00000a> JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }<Transfer transfer id=tr_103tJD2eZvKYlo2CbDua7SMQ at 0x00000a> JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }{ "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }com.stripe.model.Transfer JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }{ "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }
 

Updating a Transfer

Updates the specified transfer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

This request accepts only the description and metadata as arguments.

Arguments
description
optional, default is nullnilNonenullnullnull An arbitrary string which you can attach to a recipient object. It is displayed alongside the recipient in the web interface. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.
metadata
optional, default is { }{ }{ }{ }{ }{ } A set of key/value pairs that you can attach to a transfer object. It can be useful for storing additional information about the transfer in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to nullnilNonenullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnull, then save.
Returns

Returns the transfer object if the update succeeded. This call will returnraiseraisethrowthrowthrow an error if update parameters are invalid.

POST https://api.stripe.com/v1/transfers/{TRANSFER_ID}tr = Stripe::Transfer.retrieve({CUSTOMER_ID}) tr.description = {NEW_DESCRIPTION} ... tr.save tr = stripe.Transfer.retrieve({CUSTOMER_ID}) tr.description = {NEW_DESCRIPTION} ... tr.save() $tr = Stripe_Transfer::retrieve({CUSTOMER_ID}); $tr->description = {NEW_DESCRIPTION}; ... $tr->save(); Transfer tr = Transfer.retrieve({CUSTOMER_ID}); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("description", {NEW_DESCRIPTION}); ... tr.update(updateParams);stripe.transfers.update({CHARGE_ID}, { description: {NEW_DESCRIPTION} }); curl https://api.stripe.com/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -d "description=Transfer for test@example.com"require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" tr = Stripe::Transfer.retrieve("tr_103tJD2eZvKYlo2CbDua7SMQ") tr.description = "Transfer for test@example.com" tr.saveimport stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" tr = stripe.Transfer.retrieve("tr_103tJD2eZvKYlo2CbDua7SMQ") tr.description = "Transfer for test@example.com" tr.save()require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); $tr = Stripe_Transfer::retrieve("tr_103tJD2eZvKYlo2CbDua7SMQ"); $tr->description = "Transfer for test@example.com"; $tr->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Transfer tr = Transfer.retrieve("tr_103tJD2eZvKYlo2CbDua7SMQ"); Map<String, Object> updateParams = new HashMap<String, Object>(); updateParams.put("description", "Transfer for test@example.com"); tr.update(updateParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.transfers.update( "ch_103tJZ2eZvKYlo2CSyNNLbLP", { description: "Transfer for test@example.com" }, function(err, transfer) { // asynchronously called } ); { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "Transfer to test@example.com", "metadata": { }, "statement_description": null, "recipient": null }#<Stripe::Transfer id=tr_103tJD2eZvKYlo2CbDua7SMQ 0x00000a> JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "Transfer to test@example.com", "metadata": { }, "statement_description": null, "recipient": null }<Transfer transfer id=tr_103tJD2eZvKYlo2CbDua7SMQ at 0x00000a> JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "Transfer to test@example.com", "metadata": { }, "statement_description": null, "recipient": null }{ "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "Transfer to test@example.com", "metadata": { }, "statement_description": null, "recipient": null }com.stripe.model.Transfer JSON: { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "Transfer to test@example.com", "metadata": { }, "statement_description": null, "recipient": null }{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "Charge for test@example.com", "metadata": { }, "statement_description": null, "recipient": null }
 

Canceling a Transfer

Cancels a transfer that has previously been created. Funds will be refunded to your available balance, and the fees you were originally charged on the transfer will be refunded. You may not cancel transfers that have already been paid out, or automatic Stripe transfers.

Arguments
id
required The identifier of the transfer to be canceled.
Returns

Returns a transfer object if the cancel succeeded. ReturnsRaisesRaisesThrowsThrowsThrows an error if the transfer has already been refunded or an invalid transfer identifier was provided.

POST https://api.stripe.com/v1/transfers/{TRANSFER_ID}/cancelNo Ruby bindings available.No Python bindings available.No PHP bindings available.No Java bindings available.stripe.transfers.cancel({TRANSFER_ID}); curl https://api.stripe.com/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/cancel \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \ -X POSTNo Ruby bindings available.No Python bindings available.No PHP bindings available.No Java bindings available.var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.transfers.cancel("ch_103tJZ2eZvKYlo2CSyNNLbLP", function(err, transfer) { // asynchronously called }); { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "canceled", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, "other_transfers": [ "tr_103tJD2eZvKYlo2CbDua7SMQ" ], "account": null, "description": "STRIPE TRANSFER", "metadata": { }, "statement_description": null, "recipient": null }No Ruby bindings available.No Python bindings available.No PHP bindings available.No Java bindings available.{ "id": "ch_103tJZ2eZvKYlo2CSyNNLbLP", "object": "charge", "created": 1398046430, "livemode": false, "paid": true, "amount": 2000, "currency": "usd", "refunded": "true", "card": { "id": "card_103hgX2eZvKYlo2Ctm7ExWBB", "object": "card", "last4": "4242", "type": "Visa", "exp_month": 12, "exp_year": 2032, "fingerprint": "Xt5EWLLDS7FJjR1c", "customer": "cus_3hgX2qhVQI7rwi", "country": "US", "name": "test@madmaze.net", "address_line1": null, "address_line2": null, "address_city": null, "address_state": null, "address_zip": null, "address_country": null, "cvc_check": null, "address_line1_check": null, "address_zip_check": null }, "captured": true, "refunds": [ { "amount": 2000, "currency": "usd", "created": 1398046478, "object": "refund", "balance_transaction": "txn_3tJa9XAyjigdiY" } ], "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "failure_message": null, "failure_code": null, "amount_refunded": 2000, "customer": "cus_3hgX2qhVQI7rwi", "invoice": "in_103tIa2eZvKYlo2C8ePjFprq", "description": null, "dispute": null, "metadata": { }, "statement_description": null }
 

List all Transfers

Returns a list of existing transfers sent to third-party bank accounts or that Stripe has sent you. The transfers are returned in sorted order, with the most recently created transfers appearing first.

Arguments
created
optional A filter on the list based on the object created field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:
date
optional A filter on the list based on the object date field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:
ending_before
optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
recipient
optional Only return transfers for the recipient specified by this recipient ID.
starting_after
optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
status
optional Only return transfers that have the given status: pending, paid, or failed.
Returns

A dictionaryhashdictionaryassociative arrayMapobject with a data property that contains an array of up to limit transfers, starting after transfer starting_after. Each entry in the array is a separate transfer object. If no more transfer are available, the resulting array will be empty. If you provide a non-existent recipient ID, this call returnsraisesraisesthrowsthrowsthrows an error.

You can optionally request that the response include the total count of all transfers that match your filters. To do so, specify `include[]=total_count` in your request.

GET https://api.stripe.com/v1/transfersStripe::Transfer.allstripe.Transfer.all()Stripe_Transfer::all();Transfer.all(Map options);stripe.transfers.list(); curl https://api.stripe.com/v1/transfers?count=3 \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe" Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" Stripe::Transfer.all(:count => 3)import stripe stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2" stripe.Transfer.all(count=3)require_once('./lib/Stripe.php'); Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2"); Stripe_Transfer::all(array("count" => 3));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"; Map<String, Object> transferParams = new HashMap<String, Object>(); transferParams.put("count", 3); Transfer.all(transferParams);var stripe = require("stripe")( "sk_test_BQokikJOvBiI2HlWgH4olfQ2" ); stripe.transfers.list({ count: 3 }, function(err, transfers) { // asynchronously called }); { "object": "list", "url": "/v1/transfers", "has_more": false, "data": [ { "id": "tr_103tJD2eZvKYlo2CbDua7SMQ", "object": "transfer", "created": 1398045089, "date": 1398211200, "livemode": false, "amount": 3675029, "currency": "usd", "status": "pending", "balance_transaction": "txn_103r2T2eZvKYlo2CFgVHixMf", "summary": { "charge_gross": 3868214, "charge_fees": 192796, "charge_fee_details": [ { "amount": 129017, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "refund_gross": -400, "refund_fees": -11, "refund_fee_details": [ { "amount": -11, "currency": "usd", "type": "stripe_fee", "description": null, "application": null } ], "adjustment_gross": 0, "adjustment_fees": 0, "adjustment_fee_details": [ ], "validation_fees": 0, "validation_count": 0, "charge_count": 556, "refund_count": 3, "adjustment_count": 0, "net": 3675029, "currency": "usd", "collected_fee_gross": 0, "collected_fee_count": 0, "collected_fee_refund_gross": 0, "collected_fee_refund_count": 0 }, "transactions": { "object": "list", "total_count": 559, "has_more": true, "url": "/v1/transfers/tr_103tJD2eZvKYlo2CbDua7SMQ/transactions", "data": [ { "id": "ch_103rmT2eZvKYlo2CWnqdvMJJ", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692648, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmQ2eZvKYlo2COnmpNGyO", "type": "charge", "amount": 400, "currency": "usd", "net": 358, "created": 1397692482, "description": "Charge for test@example.com", "fee": 42, "fee_details": [ { "amount": 42, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmP2eZvKYlo2C8IA1esIS", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692425, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmM2eZvKYlo2Cxn9qkry2", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692250, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] }, { "id": "ch_103rmK2eZvKYlo2CIVE2IQEq", "type": "charge", "amount": 500, "currency": "usd", "net": 455, "created": 1397692119, "description": null, "fee": 45, "fee_details": [ { "amount": 45, "currency": "usd", "type": "stripe_fee", "description": "Stripe processing fees", "application": null } ] } ] }, &quo