API Reference

The Stripe API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.

API libraries

Libraries for the Stripe API are available in several languages.

https://api.stripe.com

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

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

To use your API key, assign it to Stripe.api_key. The Ruby library will then automatically send this key in each request.

To use your API key, assign it to stripe.api_key. The Python library will then automatically send this key in each request.

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

To use your API key, assign it to Stripe.apiKey. The Java library will then automatically send this key in each request.

To use your API key, pass it to the stripe module. The Node.js library then will automatically send this key in each request.

To use your API key, assign it to stripe.Key. The Go library will then automatically send this key in each request.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. 

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"
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cURL uses the -u flag to pass basic auth credentials (adding a colon after your API key prevents cURL from asking for a password). You can set the default API 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 the default 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 is included in all the examples on this page, so you can test any example right away. To test requests using your account, replace the sample API key with your actual API key.

Errors

Stripe uses conventional HTTP response codes to indicate the 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 failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Stripe's servers (these are rare).

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: api_connection_error, api_error, authentication_error, card_error, invalid_request_error, or rate_limit_error.

  • message optional

    A human-readable message providing 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 The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly.
500, 502, 503, 504 - Server Errors Something went wrong on Stripe's end. (These are rare.)

Errors

Types
api_connection_error Failure to connect to Stripe's API.
api_error API errors cover any other type of problem (e.g., a temporary problem with Stripe's servers) and are extremely uncommon.
authentication_error Failure to properly authenticate yourself in the request.
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.
invalid_request_error Invalid request errors arise when your request has invalid parameters.
rate_limit_error Too many requests hit the API too quickly.
Codes
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.
incorrect_number The card number is incorrect.
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.
CVC validation and zip validation can be enabled/disabled in your settings.

Handling errors

Our API libraries raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

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

begin
  # Use Stripe's library to make requests...
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::RateLimitError => e
  # Too many requests made to the API too quickly
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
end
try:
  # Use Stripe's library to make requests...
  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.RateLimitError, e:
  # Too many requests made to the API too quickly
  pass
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
  pass
try {
  // Use Stripe's library to make requests...
} catch(\Stripe\Error\Card $e) {
  // Since it's a decline, \Stripe\Error\Card 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\Error\RateLimit $e) {
  // Too many requests made to the API too quickly
} catch (\Stripe\Error\InvalidRequest $e) {
  // Invalid parameters were supplied to Stripe's API
} catch (\Stripe\Error\Authentication $e) {
  // Authentication with Stripe's API failed
  // (maybe you changed API keys recently)
} catch (\Stripe\Error\ApiConnection $e) {
  // Network communication with Stripe failed
} catch (\Stripe\Error\Base $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 library to make requests...
} 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.getMessage());
} catch (RateLimitException e) {
  // Too many requests made to the API too quickly
} 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, and instead prefers the
// asynchronous style of error handling described below.
//
// 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 'RateLimitError':
    // Too many requests made to the API too quickly
    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;
  default:
    // Handle any other types of unexpected errors
    break;
}
_, err := // Go library call

if err != nil {
  stripeErr := err.(*stripe.Error)

  switch stripeErr.Code {
  case stripe.IncorrectNum:
  case stripe.InvalidNum:
  case stripe.InvalidExpM:
  case stripe.InvalidExpY:
  case stripe.InvalidCvc:
  case stripe.ExpiredCard:
  case stripe.IncorrectCvc:
  case stripe.IncorrectZip:
  case stripe.CardDeclined:
  case stripe.Missing:
  case stripe.ProcessingErr:
  }
}

Expanding Objects

Many objects contain the ID of a related object in their response properties. For example, a Charge may have an associated Customer ID. 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 objects at once by identifying multiple items in the expand array. 

curl https://api.stripe.com/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d expand[]=customer

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.retrieve(:id => "ch_17YeVf2eZvKYlo2CbSkw0Av7", :expand => ['customer'])
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7", expand=['customer'])
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::retrieve(array("id" => "ch_17YeVf2eZvKYlo2CbSkw0Av7", "expand" => array("customer")));
The Stripe Java library does not support this feature.
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7", {
  expand: ["customer"]
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ChargeParams{}
params.Expand("customer")
charge.Get("ch_17YeVf2eZvKYlo2CbSkw0Av7", params)

Idempotent Requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a charge fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single charge is created.

To perform an idempotent request, attach a unique key to any POST request made to the API via the Idempotency-Key: <key> header.

To perform an idempotent request, provide an additional idempotency_key element to the request parameters.

To perform an idempotent request, provide a key to setIdempotencyKey() on a request.

To perform an idempotent request, provide an additional IdempotencyKey element to the request parameters.

How you create unique keys is completely up to you. We suggest using random strings or UUIDs. We'll always send back the same response for requests made with the same key. However, you cannot use the same key with different request parameters. The keys expire after 24 hours. 

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -H "Idempotency-Key: YICERqS7ESJ7vVet" \
   -d amount=400 \
   -d source=tok_17YYPH2eZvKYlo2C8ZbpILPR \
   -d currency=usd

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.create({
  :amount => 400,
  :currency => "usd",
  :source => "tok_17YYPH2eZvKYlo2C8ZbpILPR", # obtained with Stripe.js
  :description => "Charge for test@example.com"
}, {
  :idempotency_key => "YICERqS7ESJ7vVet"
})
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.create(
  amount=400,
  currency="usd",
  source="tok_17YYPH2eZvKYlo2C8ZbpILPR", # obtained with Stripe.js
  idempotency_key='YICERqS7ESJ7vVet'
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::create(array(
  "amount" => 400,
  "currency" => "usd",
  "source" => "tok_17YYPH2eZvKYlo2C8ZbpILPR", // obtained with Stripe.js
  "description" => "Charge for test@example.com"
), array(
  "idempotency_key" => "YICERqS7ESJ7vVet",
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("amount", 400);
chargeParams.put("currency", "usd");
chargeParams.put("source", "tok_17YYPH2eZvKYlo2C8ZbpILPR"); // obtained with Stripe.js
chargeParams.put("description", "Charge for test@example.com");

RequestOptions options = RequestOptions
  .builder()
  .setIdempotencyKey("YICERqS7ESJ7vVet")
  .build();

Charge.create(chargeParams, options);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.create({
  amount: 400,
  currency: "usd",
  source: "tok_17YYPH2eZvKYlo2C8ZbpILPR", // obtained with Stripe.js
  description: "Charge for test@example.com"
}, {
  idempotency_key: "YICERqS7ESJ7vVet"
}, function(err, charge) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

args := &stripe.ChargeParams{
  Amount: 400,
  Currency: "usd",
  Desc: "Charge for test@example.com",
}
args.SetSource("tok_17YYPH2eZvKYlo2C8ZbpILPR") // obtained with Stripe.js
args.Params.IdempotencyKey = "YICERqS7ESJ7vVet"
ch, err := charge.New(args)

Metadata

Updatable Stripe objects—including Account, Charge, Customer, Refund, Subscription, and Transfer—have a metadata parameter. You can use this parameter to attach key-value data to these Stripe objects.

Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on a Stripe Customer object. Metadata is not used by Stripe (e.g., to authorize or decline a charge), and won't be seen by your users unless you choose to show it to them.

Some of the objects listed above also support a description parameter. 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". Unlike metadata, description is a single string, and your users may see it (e.g., in email receipts Stripe sends on your behalf).

Note: You can have up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

Sample metadata use cases

  • Link IDs

    Attach your system's unique IDs to a Stripe object for easy lookups. Add your order number to a charge, your user ID to a customer or recipient, or a unique receipt number to a transfer, for example.

  • Refund papertrails

    Store information about why a refund was created, and by whom.

  • Customer details

    Annotate a customer by storing the customer's phone number for your later use. 

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=400 \
   -d currency=usd \
   -d source=tok_17YYPH2eZvKYlo2C8ZbpILPR \
   -d metadata[order_id]=6735

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.create(
  :amount => 400,
  :currency => "usd",
  :source => "tok_17YYPH2eZvKYlo2C8ZbpILPR", # obtained with Stripe.js,
  :metadata => {'order_id' => '6735'}
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.create(
  amount=400,
  currency="usd",
  source="tok_17YYPH2eZvKYlo2C8ZbpILPR", # obtained with Stripe.js
  metadata={'order_id': '6735'}
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::create(array(
  "amount" => 400,
  "currency" => "usd",
  "source" => "tok_17YYPH2eZvKYlo2C8ZbpILPR", // 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("source", "tok_17YYPH2eZvKYlo2C8ZbpILPR"); // obtained with Stripe.js
chargeParams.put("description", "Charge for test@example.com");
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",
  source: "tok_17YYPH2eZvKYlo2C8ZbpILPR", // obtained with Stripe.js
  metadata: {'order_id': '6735'}
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ChargeParams{
  Amount: 400,
  Currency: "usd",
}
params.SetSource("tok_17YYPH2eZvKYlo2C8ZbpILPR") // obtained with Stripe.js
params.AddMeta("order_id", "6735")
charge.New(params)
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 at 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance you can list charges, list customers, and list invoices. These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before.

Stripe utilizes cursor-based pagination via the starting_after and ending_before parameters. Both take an existing object ID value (see below). The ending_before parameter returns objects created before the named object, in descending chronological order. The starting_after parameter returns objects created after the named object, in ascending chronological order. If both parameters are provided, only ending_before is used.

Arguments

  • limit optional

    A limit on the number of objects to be returned, between 1 and 100.

  • 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"

    A string describing the object type returned.

  • 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 set. If false, this set comprises the end of the list.

  • url string

    The URL for accessing this list. 

curl https://api.stripe.com/v1/customers?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("limit", 3);

Customer.all(customerParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.list(
  { limit: 3 },
  function(err, customers) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CustomerListParams{}
params.Filters.AddFilter("limit", "", "3")
i := customer.List(params)
for i.Next() {
  c := i.Customer()
}
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    #<Stripe::Customer id=cus_7oGjJvWit3N9Ps 0x00000a> JSON: {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    },
    #<Stripe::Customer[...] ...>,
    #<Stripe::Customer[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers",
  has_more: false,
  data: [
    <Customer customer id=cus_7oGjJvWit3N9Ps at 0x00000a> JSON: {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    },
    <stripe.Customer[...] ...>,
    <stripe.Customer[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Customer JSON: {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    }
    [1] => <Stripe\Customer[...] ...>
    [2] => <Stripe\Customer[...] ...>
  ]
}
#<com.stripe.model.CustomerCollection id=#> JSON: {
  "data": [
    com.stripe.model.Customer JSON: {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    },
    #<com.stripe.model.Customer[...] ...>,
    #<com.stripe.model.Customer[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    },
    {...},
    {...}
  ]
}
&stripe.Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers in the URLs of individual request logs in your Dashboard. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Versioning

When we make backwards-incompatible changes to the API, we release new, dated versions. The current version is 2015-10-16. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests will use your account API settings, unless you override the API version. The changelog lists every available version. Note that events generated by API requests will always be structured according to your account API version.

To set the API version on a specific request, send a Stripe-Version header.

To override the API version, assign the version to the Stripe.api_version property.

To override the API version, assign the version to the stripe.api_version property.

To override the API version, assign the version to the Stripe.apiVersion property.

To override the API version, pass the version to the \Stripe\Stripe::setApiVersion() method.

To override the API version, pass the version to the stripe.setApiVersion() method.

Since Go is strongly typed, the version is fixed in the library. Revert to an older version of the library to change the API version used.

You can visit your Dashboard to upgrade your API version. As a precaution, use API versioning to test a new API version before committing to an upgrade. 

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -H "Stripe-Version: 2015-10-16"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
Stripe.api_version = "2015-10-16"
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
stripe.api_version = '2015-10-16'
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
\Stripe\Stripe::setApiVersion("2015-10-16");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
Stripe.apiVersion = "2015-10-16";
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);
stripe.setApiVersion('2015-10-16');
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
// Since Go is strongly typed,
// the version is fixed in the library.

Balance

This is an object representing your Stripe balance. You can retrieve it to see the balance currently on your Stripe account.

You can also retrieve a list of the balance history, which contains a list of transactions that contributed to the balance (e.g., charges, transfers, and so forth).

The available and pending amounts for each currency are broken down further by payment source types.

The balance object

Attributes

  • object string , value is "balance"

  • available array

    Funds that are available to be paid out automatically by Stripe or explicitly via the transfers API. The available balance for each currency and payment type can be found in the source_types property.

  • livemode boolean

  • pending array

    Funds that are not available in the balance yet, due to the 7-day rolling pay cycle. The pending balance for each currency and payment type can be found in the source_types property 

{
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
#<Stripe::Balance 0x00000a> JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
<Balance balance at 0x00000a> JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
Stripe\Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
com.stripe.model.Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
{
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
&stripe.Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}

The balance_transaction object

Attributes

  • id string

  • object string , value is "balance_transaction"

  • amount integer

    Gross amount of the transaction, in cents.

  • available_on timestamp

    The date the transaction’s net funds will become available in the Stripe balance.

  • created timestamp

  • currency currency

  • description string

  • fee integer

    Fees (in cents) paid for this transaction

  • fee_details list

    Detailed breakdown of fees (in cents) paid for this transaction

    child attributes

    • amount integer

    • application string

    • currency currency

    • description string

    • type string

      Type of the fee, one of: application_fee, stripe_fee or tax.

  • net integer

    Net amount of the transaction, in cents.

  • source string

    The Stripe object this transaction is related to.

  • sourced_transfers list

    The transfers (if any) for which source is a source_transaction.

    child attributes

    • object string , value is "list"

    • data array, contains: transfer object

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • status string

    If the transaction’s net funds are available in the Stripe balance yet. Either available or pending.

  • type string

    Type of the transaction, one of: charge, refund, adjustment, application_fee, application_fee_refund, transfer, transfer_cancel, transfer_refund, or transfer_failure. 

{
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
#<Stripe::BalanceTransaction id=txn_17WEDl2eZvKYlo2CxRlP8kcb 0x00000a> JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
<BalanceTransaction balance_transaction id=txn_17WEDl2eZvKYlo2CxRlP8kcb at 0x00000a> JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
Stripe\BalanceTransaction JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
com.stripe.model.BalanceTransaction JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
{
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
&stripe.BalanceTransaction JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}

Retrieve balance

Retrieves the current account balance, based on the authentication that was used to make the request.

Arguments

  • No arguments…

Returns

Returns a balance object for the account authenticated as.

curl https://api.stripe.com/v1/balance \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Balance.retrieve()
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Balance.retrieve()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Balance::retrieve();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Balance.retrieve();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.balance.retrieve(function(err, balance) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

b, err := balance.Get(nil)
 
{
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
#<Stripe::Balance 0x00000a> JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
<Balance balance at 0x00000a> JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
Stripe\Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
com.stripe.model.Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
{
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}
&stripe.Balance JSON: {
  "object": "balance",
  "available": [
    {
      "currency": "usd",
      "amount": 7860735958,
      "source_types": {
        "card": 7852835784,
        "bank_account": 6513784,
        "bitcoin_receiver": 1386390
      }
    }
  ],
  "livemode": false,
  "pending": [
    {
      "currency": "usd",
      "amount": 81934039,
      "source_types": {
        "card": 81934039,
        "bank_account": 0,
        "bitcoin_receiver": 0
      }
    }
  ]
}

Retrieve a balance transaction

Retrieves the balance transaction with the given ID.

Arguments

  • id required

    The ID of the desired balance transaction (as found on any API object that affects the balance, e.g. a charge or transfer).

Returns

Returns a balance transaction if a valid balance transaction ID was provided. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error otherwise.

curl https://api.stripe.com/v1/balance/history/txn_17WEDl2eZvKYlo2CxRlP8kcb \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::BalanceTransaction.retrieve("txn_17WEDl2eZvKYlo2CxRlP8kcb")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.BalanceTransaction.retrieve("txn_17WEDl2eZvKYlo2CxRlP8kcb")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\BalanceTransaction::retrieve("txn_17WEDl2eZvKYlo2CxRlP8kcb");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

BalanceTransaction.retrieve("txn_17WEDl2eZvKYlo2CxRlP8kcb");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.balance.retrieveTransaction(
  "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  function(err, balanceTransaction) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

tx, err := balance.GetTx("txn_17WEDl2eZvKYlo2CxRlP8kcb", nil)
 
{
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
#<Stripe::BalanceTransaction id=txn_17WEDl2eZvKYlo2CxRlP8kcb 0x00000a> JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
<BalanceTransaction balance_transaction id=txn_17WEDl2eZvKYlo2CxRlP8kcb at 0x00000a> JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
Stripe\BalanceTransaction JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
com.stripe.model.BalanceTransaction JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
{
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}
&stripe.BalanceTransaction JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}

List all balance history

Returns a list of transactions that have contributed to the Stripe account balance (e.g., charges, transfers, and so forth). The transactions are returned in sorted order, with the most recent transactions appearing first.

Arguments

  • available_on optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object available_on field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the available_on field is after this timestamp.

    • gte optional

      Return values where the available_on field is after or equal to this timestamp.

    • lt optional

      Return values where the available_on field is before this timestamp.

    • lte optional

      Return values where the available_on field is before or equal to this timestamp.

  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • currency optional

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

  • source optional

    Only returns transactions that are related to the specified Stripe object ID (e.g. filtering by a charge ID will return all related charge transactions).

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

  • transfer optional

    For automatic Stripe transfers only, only returns transactions that were transferred out on the specified transfer ID.

  • type optional

    Only returns transactions of the given type. One of: charge, adjustment, application_fee, application_fee_refund, transfer, or transfer_failure

Returns

A dictionaryhashdictionaryassociative arrayMapobjectmap with a data property that contains an array of up to limit transactions, starting after transaction starting_after. Each entry in the array is a separate transaction history object. If no more transactions are available, the resulting array will be empty.

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

GET https://api.stripe.com/v1/balance/history
Stripe::BalanceTransaction.all
stripe.BalanceTransaction.all()
\Stripe\BalanceTransaction::all();
BalanceTransaction.all();
stripe.balance.listTransactions();
balance.List()
 
curl https://api.stripe.com/v1/balance/history?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::BalanceTransaction.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.BalanceTransaction.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\BalanceTransaction::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> balanceTransactionParams = new HashMap<String, Object>();
balanceTransactionParams.put("limit", 3);

Balancetransaction.all(balanceTransactionParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.balance.listTransactions({ limit: 3 }, function(err, transactions) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.TxListParams{}
params.Filters.AddFilter("limit", "", "3")
i := balance.List(params)
for i.Next() {
  tx := i.Transaction()
}
 
{
  "object": "list",
  "url": "/v1/balance/history",
  "has_more": false,
  "data": [
    {
      "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "object": "balance_transaction",
      "amount": 35060,
      "available_on": 1454025600,
      "created": 1453504897,
      "currency": "usd",
      "description": "1 Month Service",
      "fee": 1047,
      "fee_details": [
        {
          "amount": 1047,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 34013,
      "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
      },
      "status": "pending",
      "type": "charge"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/balance/history",
  "has_more": false,
  "data": [
    #<Stripe::BalanceTransaction id=txn_17WEDl2eZvKYlo2CxRlP8kcb 0x00000a> JSON: {
      "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "object": "balance_transaction",
      "amount": 35060,
      "available_on": 1454025600,
      "created": 1453504897,
      "currency": "usd",
      "description": "1 Month Service",
      "fee": 1047,
      "fee_details": [
        {
          "amount": 1047,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 34013,
      "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
      },
      "status": "pending",
      "type": "charge"
    },
    #<Stripe::BalanceTransaction[...] ...>,
    #<Stripe::BalanceTransaction[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/balance/history",
  has_more: false,
  data: [
    <BalanceTransaction balance_transaction id=txn_17WEDl2eZvKYlo2CxRlP8kcb at 0x00000a> JSON: {
      "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "object": "balance_transaction",
      "amount": 35060,
      "available_on": 1454025600,
      "created": 1453504897,
      "currency": "usd",
      "description": "1 Month Service",
      "fee": 1047,
      "fee_details": [
        {
          "amount": 1047,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 34013,
      "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
      },
      "status": "pending",
      "type": "charge"
    },
    <stripe.BalanceTransaction[...] ...>,
    <stripe.BalanceTransaction[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/balance/history",
  "has_more" => false,
  "data" => [
    [0] => Stripe\BalanceTransaction JSON: {
      "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "object": "balance_transaction",
      "amount": 35060,
      "available_on": 1454025600,
      "created": 1453504897,
      "currency": "usd",
      "description": "1 Month Service",
      "fee": 1047,
      "fee_details": [
        {
          "amount": 1047,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 34013,
      "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
      },
      "status": "pending",
      "type": "charge"
    }
    [1] => <Stripe\BalanceTransaction[...] ...>
    [2] => <Stripe\BalanceTransaction[...] ...>
  ]
}
#<com.stripe.model.BalanceTransactionCollection id=#> JSON: {
  "data": [
    com.stripe.model.BalanceTransaction JSON: {
      "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "object": "balance_transaction",
      "amount": 35060,
      "available_on": 1454025600,
      "created": 1453504897,
      "currency": "usd",
      "description": "1 Month Service",
      "fee": 1047,
      "fee_details": [
        {
          "amount": 1047,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 34013,
      "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
      },
      "status": "pending",
      "type": "charge"
    },
    #<com.stripe.model.BalanceTransaction[...] ...>,
    #<com.stripe.model.BalanceTransaction[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/balance/history",
  "has_more": false,
  "data": [
    {
      "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "object": "balance_transaction",
      "amount": 35060,
      "available_on": 1454025600,
      "created": 1453504897,
      "currency": "usd",
      "description": "1 Month Service",
      "fee": 1047,
      "fee_details": [
        {
          "amount": 1047,
          "application": null,
          "currency": "usd",
          "description": "Stripe processing fees",
          "type": "stripe_fee"
        }
      ],
      "net": 34013,
      "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
      "sourced_transfers": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
      },
      "status": "pending",
      "type": "charge"
    },
    {...},
    {...}
  ]
}
&stripe.BalanceTransaction JSON: {
  "id": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "object": "balance_transaction",
  "amount": 35060,
  "available_on": 1454025600,
  "created": 1453504897,
  "currency": "usd",
  "description": "1 Month Service",
  "fee": 1047,
  "fee_details": [
    {
      "amount": 1047,
      "application": null,
      "currency": "usd",
      "description": "Stripe processing fees",
      "type": "stripe_fee"
    }
  ],
  "net": 34013,
  "source": "ch_17WEDl2eZvKYlo2CYZHr0AI4",
  "sourced_transfers": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers?source_transaction=ch_17WEDl2eZvKYlo2CYZHr0AI4"
  },
  "status": "pending",
  "type": "charge"
}

Charges

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

The charge object

Attributes

  • id string

  • object string , value is "charge"

  • amount positive integer or zero

    Amount charged in cents

  • 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).

  • application_fee string

    The application fee (if any) for the charge. See the Connect documentation for details.

  • balance_transaction string

    ID of the balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes).

  • captured boolean

    If the charge was created without capturing, this boolean represents whether or not it is still uncaptured or has since been captured.

  • created timestamp

  • currency currency

    Three-letter ISO currency code representing the currency in which the charge was made.

  • customer string

    ID of the customer this charge is for if one exists.

  • description string

  • destination string

    The account (if any) the charge was made on behalf of. See the Connect documentation for details.

  • 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 the errors section for a list of codes).

  • failure_message string

    Message to user further explaining reason for charge failure if available.

  • fraud_details hash

    Hash with information on fraud assessments for the charge. Assessments reported by you have the key user_report and, if set, possible values of safe and fraudulent. Assessments from Stripe have the key stripe_report and, if set, the value fraudulent.

  • invoice string

    ID of the invoice this charge is for if one exists.

  • livemode boolean

  • metadata #

    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.

  • order string

    ID of the order this charge is for if one exists.

  • paid boolean

    true if the charge succeeded, or was successfully authorized for later capture.

  • receipt_email string

    This is the email address that the receipt for this charge was sent to.

  • receipt_number string

    This is the transaction number that appears on email receipts sent for this charge.

  • 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 list

    A list of refunds that have been applied to the charge.

    child attributes

    • object string , value is "list"

    • data list

      child attributes

      • id string

      • object string , value is "list"

      • amount integer

        Amount, in cents.

      • balance_transaction string

        Balance transaction that describes the impact on your account balance.

      • charge string

        ID of the charge that was refunded.

      • created timestamp

      • currency currency

        Three-letter ISO code representing the currency.

      • description string

      • metadata #

        A set of key/value pairs that you can attach to the object. It can be useful for storing additional information in a structured format.

      • reason string

        Reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer.

      • receipt_number string

        This is the transaction number that appears on email receipts sent for this refund.

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • shipping hash

    Shipping information for the charge.

    child attributes

    • address hash

      Shipping address.

      child attributes

      • city string

        City/Suburb/Town/Village

      • country string

        2-letter country code

      • line1 string

        Address line 1 (Street address/PO Box/Company name)

      • line2 string

        Address line 2 (Apartment/Suite/Unit/Building)

      • postal_code string

        Zip/Postal Code

      • state string

        State/Province/County

    • carrier string

      The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc.

    • name string

      Recipient name.

    • phone string

      Recipient phone (including extension).

    • tracking_number string

      The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.

  • statement_descriptor string

    Extra information about a charge. This will appear on your customer’s credit card statement.

  • status string

    The status of the payment is either succeeded or failed.

  • transfer string

    ID of the transfer to the destination account (only applicable if the charge was created using the destination parameter). 

{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 at 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

Create a charge

To charge a credit card, you create a charge object. If your API key is in test mode, the supplied payment source (e.g., card or Bitcoin receiver) 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.

  • application_fee connect only optional

    A fee in cents that will be applied to the charge and transferred to the application owner's Stripe account. To use an application fee, the request must be made on behalf of another account, using the Stripe-Account header, an OAuth key, or the destination parameter. For more information, see the application fees documentation.

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

  • description optional, default is nullnilNonenullnullnullnull

    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.

  • destination connect only optional

    An account to make the charge on behalf of. If specified, the charge will be attributed to the destination account for tax reporting, and the funds from the charge will be transferred to the destination account. The ID of the resulting transfer will be returned in the transfer field of the response. See the documentation for details.

  • 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 customer in a structured format. It's often a good idea to store an email address in metadata for tracking later.

  • receipt_email optional, default is nullnilNonenullnullnullnull

    The email address to send this charge's receipt to. The receipt will not be sent until the charge is paid. If this charge is for a customer, the email address specified here will override the customer's email address. Receipts will not be sent for test mode charges. If receipt_email is specified for a charge in live mode, a receipt will be sent regardless of your email settings.

  • shipping optional, default is { }

    Shipping information for the charge. Helps prevent fraud on charges for physical goods.

  • customer optional, either customer or source is required

    The ID of an existing customer that will be charged in this request.

  • source optional, either source or customer is required

    A payment source to be charged, such as a credit card. If you also pass a customer ID, the source must be the ID of a source belonging to the customer. Otherwise, if you do not pass a customer ID, the source you provide must either be a token, like the ones returned by Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's credit card details, with the options described below. Although not all information is required, the extra info helps prevent fraud.

    child attributes

    • exp_monthexp_monthexp_monthexp_monthexp_monthexp_monthexp_month required

      Two digit number representing the card's expiration month.

    • exp_yearexp_yearexp_yearexp_yearexp_yearexp_yearexp_year required

      Two or four digit number representing the card's expiration year.

    • numbernumbernumbernumbernumbernumbernumber required

      The card number, as a string without any separators.

    • objectobjectobjectobjectobjectobjectobject required

      The type of payment source. Should be "card".

    • cvccvccvccvccvccvccvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city optional

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • namenamenamenamenamenamename optional

      Cardholder's full name.

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

  • statement_descriptor optional, default is nullnilNonenullnullnullnull

    An arbitrary string to be displayed on your customer's credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you're charging for is a race ticket, you may want to specify a statement_descriptor of RunClub 5K race ticket. The statement description may not include <>"' characters, and will appear on your customer's statement in capital letters. Non-ASCII characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all.

Returns

Returns a charge object if the charge succeeded. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an 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 cvccvccvccvccvccvccvc 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_line1address_line1 or address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip are provided, Stripe will 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 'unavailable' 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/charges
Stripe::Charge.create
stripe.Charge.create()
\Stripe\Charge::create();
Charge.create();
stripe.charges.create();
charge.New()
curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=400 \
   -d currency=usd \
   -d source=tok_17YYPH2eZvKYlo2C8ZbpILPR \
   -d description="Charge for test@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.create(
  :amount => 400,
  :currency => "usd",
  :source => "tok_17YYPH2eZvKYlo2C8ZbpILPR", # 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",
  source="tok_17YYPH2eZvKYlo2C8ZbpILPR", # obtained with Stripe.js
  description="Charge for test@example.com"
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::create(array(
  "amount" => 400,
  "currency" => "usd",
  "source" => "tok_17YYPH2eZvKYlo2C8ZbpILPR", // 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("source", "tok_17YYPH2eZvKYlo2C8ZbpILPR"); // obtained with Stripe.js
chargeParams.put("description", "Charge for test@example.com");

Charge.create(chargeParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.create({
  amount: 400,
  currency: "usd",
  source: "tok_17YYPH2eZvKYlo2C8ZbpILPR", // obtained with Stripe.js
  description: "Charge for test@example.com"
}, function(err, charge) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

chargeParams := &stripe.ChargeParams{
  Amount: 400,
  Currency: "usd",
  Desc: "Charge for test@example.com",
}
chargeParams.SetSource("tok_17YYPH2eZvKYlo2C8ZbpILPR")
ch, err := charge.New(chargeParams)
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 at 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

Verification responses

CVC source[cvc_check]
pass The CVC provided is correct.
fail The CVC provided is incorrect.
unavailable The customer's bank did not check the CVC provided.
unchecked The CVC was provided but has not yet been checked. Checks are performed once a card is attached to a Customer object, or when a Charge is created.
Address line source[address_line1_check]
pass The first address line provided is correct.
fail The first address line provided is incorrect.
unavailable The customer's bank did not check the first address line provided.
unchecked The first address line was provided but has not yet been checked. Checks are performed once a card is attached to a Customer object, or when a Charge is created.
Address ZIP source[address_zip_check]
pass The ZIP code provided is correct.
fail The ZIP code provided is incorrect.
unavailable The customer's bank did not check the ZIP code.
unchecked The ZIP code was provided but has not yet been checked. Checks are performed once a card is attached to a Customer object, or when a Charge is created.

Retrieve 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

  • charge required

    The identifier of the charge to be retrieved.

Returns

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

curl https://api.stripe.com/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.retrieve(
  "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  function(err, charge) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := charge.Get("ch_17YeVf2eZvKYlo2CbSkw0Av7", nil)
 
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 at 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

Update 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, metadata, receipt_email, fraud_details, and shipping as arguments.

Arguments

  • description optional, default is nullnilNonenullnullnullnull

    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. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • fraud_details optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs you can attach to a charge giving information about its riskiness. If you believe a charge is fraudulent, include a user_report key with a value of fraudulent. If you believe a charge is safe, include a user_report key with a value of safe. Note that you must refund a charge before setting the user_report to fraudulent. Stripe will use the information you send to improve our fraud detection algorithms.

  • 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 nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

  • receipt_email optional, default is nullnilNonenullnullnullnull

    This is the email address that the receipt for this charge will be sent to. If this field is updated, then a new email receipt will be sent to the updated address.

  • shipping optional, default is { }

    Shipping information for the charge. Helps prevent fraud on charges for physical goods.

Returns

Returns the charge object if the update succeeded. This call will returnraiseraisethrowthrowthrowreturn an 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}
...
ch.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}
});
charge.Update({CHARGE_ID}, &stripe.ChargeParams{Desc: {NEW_DESCRIPTION}})
curl https://api.stripe.com/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Charge for test@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7")
ch.description = "Charge for test@example.com"
ch.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7")
ch.description = "Charge for test@example.com"
ch.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = \Stripe\Charge::retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7");
$ch->description = "Charge for test@example.com";
$ch->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge ch = Charge.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7");
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_17YeVf2eZvKYlo2CbSkw0Av7",
  {
    description: "Charge for test@example.com"
  },
  function(err, charge) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch, err := charge.Update(
  "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  &stripe.ChargeParams{Desc: "Charge for test@example.com"},
)
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 at 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "Charge for test@example.com",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

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

  • charge 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.

  • receipt_email optional

    The email address to send this charge’s receipt to. This will override the previously-specified email address for this charge, if one was set. Receipts will not be sent in test mode.

  • statement_descriptor optional

    An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you’re charging for is a race ticket, you may want to specify a statement_descriptor of RunClub 5K race ticket. The statement description may not include <>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. Updating this value will overwrite the previous statement descriptor of this charge. While most banks display this information consistently, some may display it incorrectly or not at all.

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, expired, captured, or an invalid capture amount is specified, in which case this method will returnraiseraisethrowthrowthrowreturn an an error.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/capture
ch = 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});
charge.Capture({CHARGE_ID})
 
curl https://api.stripe.com/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/capture \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7")
ch.capture
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7")
ch.capture()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = \Stripe\Charge::retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7");
$ch->capture();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

ch = Charge.retrieve("ch_17YeVf2eZvKYlo2CbSkw0Av7");
ch.capture();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.capture("ch_17YeVf2eZvKYlo2CbSkw0Av7", function(err, charge) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch, err := charge.Capture("ch_17YeVf2eZvKYlo2CbSkw0Av7", nil)
 
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
#<Stripe::Charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
<Charge charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 at 0x00000a> JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": "True",
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
Stripe\Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
com.stripe.model.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": "true",
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
{
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": "true",
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}
&stripe.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": "true",
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

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 dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

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

  • source optional dictionaryhashdictionaryassociative arrayMapobjectmap, default is { object: 'all' }

    A filter on the list based on the source of the charge. The value can be a dictionary with the following options:

    child arguments

    • object optional

      Return charges that match this source type string. Available options are all, alipay_account, bitcoin_receiver, or card.

  • 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 arrayMapobjectmap 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 returnsraisesraisesthrowsthrowsthrowsreturns 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/charges
Stripe::Charge.all
stripe.Charge.all()
\Stripe\Charge::all();
Charge.all(Map<String, Object> options);
stripe.charges.list();
charge.List()
 
curl https://api.stripe.com/v1/charges?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("limit", 3);

Charge.all(chargeParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.list(
  { limit: 3 },
  function(err, charges) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ChargeListParams{}
params.Filters.AddFilter("limit", "", "3")
i := charge.List(params)
for i.Next() {
  c := i.Charge()
}
 
{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    #<Stripe::Charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 0x00000a> JSON: {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    },
    #<Stripe::Charge[...] ...>,
    #<Stripe::Charge[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/charges",
  has_more: false,
  data: [
    <Charge charge id=ch_17YeVf2eZvKYlo2CbSkw0Av7 at 0x00000a> JSON: {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    },
    <stripe.Charge[...] ...>,
    <stripe.Charge[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/charges",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Charge JSON: {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
    [1] => <Stripe\Charge[...] ...>
    [2] => <Stripe\Charge[...] ...>
  ]
}
#<com.stripe.model.ChargeCollection id=#> JSON: {
  "data": [
    com.stripe.model.Charge JSON: {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    },
    #<com.stripe.model.Charge[...] ...>,
    #<com.stripe.model.Charge[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    },
    {...},
    {...}
  ]
}
&stripe.Charge JSON: {
  "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "object": "charge",
  "amount": 5001,
  "amount_refunded": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "captured": true,
  "created": 1454082607,
  "currency": "usd",
  "customer": null,
  "description": "User: 590. Events: 966. Total Tickets: 1.",
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": null,
  "livemode": false,
  "metadata": {
    "user_id": "590",
    "seller_id": "797",
    "events": "PHPUNIT Demo",
    "event_ids": "966"
  },
  "order": null,
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
  },
  "shipping": null,
  "source": {
    "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
    "object": "card",
    "address_city": "Pittsburgh",
    "address_country": "US",
    "address_line1": "414 Grant St",
    "address_line1_check": "pass",
    "address_line2": null,
    "address_state": "PA",
    "address_zip": "15219",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": null,
    "cvc_check": "pass",
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2022,
    "funding": "unknown",
    "last4": "1111",
    "metadata": {
    },
    "name": "Harold Hamburger",
    "tokenization_method": null
  },
  "statement_descriptor": null,
  "status": "succeeded"
}

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"

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

  • created timestamp

  • currency string

    The currency the customer can be charged in for recurring billing purposes (subscriptions, invoices, invoice items).

  • default_source string

    ID of the default source attached to this customer.

  • 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

  • livemode boolean

  • metadata #

    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.

  • shipping hash

    Shipping information associated with the customer.

    child attributes

    • address hash

      Customer shipping address.

      child attributes

      • city string

        City/Suburb/Town/Village

      • country string

        2-letter country code

      • line1 string

        Address line 1 (Street address/PO Box/Company name)

      • line2 string

        Address line 2 (Apartment/Suite/Unit/Building)

      • postal_code string

        Zip/Postal Code

      • state string

        State/Province/County

    • name string

      Customer name.

    • phone string

      Customer phone (including extension).

  • sources list

    The customer’s payment sources, if any

    child attributes

    • object string , value is "list"

    • data array

      The list contains all payment sources that have been attached to the customer. These may be Cards or BitcoinReceivers.

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • subscriptions list

    The customer’s current subscriptions, if any

    child attributes

    • object string , value is "list"

    • data array, contains: subscription object

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed. 

{
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
#<Stripe::Customer id=cus_7oGjJvWit3N9Ps 0x00000a> JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
<Customer customer id=cus_7oGjJvWit3N9Ps at 0x00000a> JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
Stripe\Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
com.stripe.model.Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
{
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
&stripe.Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}

Create a 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.

  • 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 nullnilNonenullnullnullnull 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 nullnilNonenullnullnullnull 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 nullnilNonenullnullnullnull and then saving.

  • plan optional

    The identifier of the plan to subscribe the customer to. If provided, the returned customer object will have a list of subscriptions that the customer is currently subscribed to. If you subscribe a customer to a plan without a free trial, the customer must have a valid card as well.

  • quantity optional

    The quantity you’d like to apply to the subscription you’re creating (if you pass in a plan). 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.

  • shipping optional dictionaryhashdictionaryassociative arrayMapobjectmap

    child arguments

    • address required

      child arguments

      • line1 required

      • city optional

      • country optional

      • line2 optional

      • postal_code optional

      • state optional

    • name required

    • phone optional

  • source optional dictionaryhashdictionaryassociative arrayMapobjectmap

    The source 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).

    child arguments

    • object required

      The type of payment source. Should be "card".

    • exp_month required

      Two digit number representing the card's expiration month.

    • exp_year required

      Two or four digit number representing the card's expiration year.

    • number required

      The card number, as a string without any separators.

    • address_city optional

    • address_country optional

    • address_line1 optional

    • address_line2 optional

    • address_state optional

    • address_zip optional

    • currency managed accounts only

      Required when adding a card to an account (not applicable to a customers or recipients). The card (which must be a debit card) can be used as a transfer destination for funds in this currency. Currently, the only supported currency for debit card transfers is usd.

    • cvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • default_for_currency managed accounts only

      Only applicable on accounts (not customers or recipients). If you set this to true (or if this is the first external account being added in this currency) this card will become the default external account for its currency.

    • metadata optional

      A set of key/value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format.

    • name optional

      Cardholder's full name.

  • tax_percent optional

    A positive decimal (with at most two decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice. Can only be used if a plan is provided.

  • trial_end optional

    Unix timestamp representing the end of the trial period the customer will get before being charged. 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 payment sources, if that information has been provided. If an invoice payment is due and a source is not provided, the call will returnraiseraisethrowthrowthrowreturn an an error. If a non-existent plan or a non-existent or expired coupon is provided, the call will returnraiseraisethrowthrowthrowreturn an an error.

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

POST https://api.stripe.com/v1/customers
Stripe::Customer.create
stripe.Customer.create()
\Stripe\Customer::create();
Customer.create();
stripe.customers.create();
customer.New()
 
curl https://api.stripe.com/v1/customers \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Customer for test@example.com" \
   -d source=tok_17YYPH2eZvKYlo2C8ZbpILPR

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.create(
  :description => "Customer for test@example.com",
  :source => "tok_17YYPH2eZvKYlo2C8ZbpILPR" # obtained with Stripe.js
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.create(
  description="Customer for test@example.com",
  source="tok_17YYPH2eZvKYlo2C8ZbpILPR" # obtained with Stripe.js
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::create(array(
  "description" => "Customer for test@example.com",
  "source" => "tok_17YYPH2eZvKYlo2C8ZbpILPR" // 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("source", "tok_17YYPH2eZvKYlo2C8ZbpILPR"); // obtained with Stripe.js

Customer.create(customerParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.create({
  description: 'Customer for test@example.com',
  source: "tok_17YYPH2eZvKYlo2C8ZbpILPR" // obtained with Stripe.js
}, function(err, customer) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customerParams := &stripe.CustomerParams{
  Desc: "Customer for test@example.com",
}
customerParams.SetSource("tok_17YYPH2eZvKYlo2C8ZbpILPR") // obtained with Stripe.js
c, err := customer.New(customerParams)
 
{
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
#<Stripe::Customer id=cus_7oGjJvWit3N9Ps 0x00000a> JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
<Customer customer id=cus_7oGjJvWit3N9Ps at 0x00000a> JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
Stripe\Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
com.stripe.model.Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
{
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
&stripe.Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}

Retrieve a customer

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

Arguments

  • customer 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.

curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer.retrieve("cus_7oGjJvWit3N9Ps");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.retrieve(
  "cus_7oGjJvWit3N9Ps",
  function(err, customer) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := customer.Get("cus_7oGjJvWit3N9Ps", nil)
 
{
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
#<Stripe::Customer id=cus_7oGjJvWit3N9Ps 0x00000a> JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
<Customer customer id=cus_7oGjJvWit3N9Ps at 0x00000a> JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
Stripe\Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
com.stripe.model.Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
{
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
&stripe.Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}

Update 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 source parameter, that becomes the customer's active source (e.g., a card) to be used for all charges in the future. When you update a customer to a new valid source: for each of the customer's current subscriptions, if the subscription is in the past_due state, then the latest unpaid, unclosed invoice for the subscription will be retried (note that this retry will not count as an automatic retry, and will not affect the next regularly scheduled payment for the invoice). (Note also that no invoices pertaining to subscriptions in the unpaid state, or invoices pertaining to canceled subscriptions, will be retried as a result of updating the customer's source.)

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

Arguments

  • account_balance optional

    An integer amount in cents that represents the account balance for your customer. Account balances only affect invoices. A negative amount represents a credit that decreases the amount due on an invoice; a positive amount increases the amount due on an invoice.

  • 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_source optional

    ID of source 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 nullnilNonenullnullnullnull 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 nullnilNonenullnullnullnull 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 nullnilNonenullnullnullnull and then saving.

  • shipping optional dictionaryhashdictionaryassociative arrayMapobjectmap

    child arguments

    • address required

      child arguments

      • line1 required

      • city optional

      • country optional

      • line2 optional

      • postal_code optional

      • state optional

    • name required

    • phone optional

  • source optional dictionaryhashdictionaryassociative arrayMapobjectmap

    The source 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 source will create a new source object, make it the new customer default source, and delete the old customer default if one exists. If you want to add additional sources 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.

    child arguments

    • object required

      The type of payment source. Should be "card".

    • exp_month required

      Two digit number representing the card's expiration month.

    • exp_year required

      Two or four digit number representing the card's expiration year.

    • number required

      The card number, as a string without any separators.

    • address_city optional

    • address_country optional

    • address_line1 optional

    • address_line2 optional

    • address_state optional

    • address_zip optional

    • currency managed accounts only

      Required when adding a card to an account (not applicable to a customers or recipients). The card (which must be a debit card) can be used as a transfer destination for funds in this currency. Currently, the only supported currency for debit card transfers is usd.

    • cvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • default_for_currency managed accounts only

      Only applicable on accounts (not customers or recipients). If you set this to true (or if this is the first external account being added in this currency) this card will become the default external account for its currency.

    • metadata optional

      A set of key/value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format.

    • name optional

      Cardholder's full name.

Returns

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

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},
  ...
});
customer.Update(
  {CUSTOMER_ID},
  &stripe.CustomerParams{
    Desc: {NEW_DESCRIPTION},
    ...
  })
 
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Customer for test@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
cu.description = "Customer for test@example.com"
cu.source = "tok_17YYPH2eZvKYlo2C8ZbpILPR" # obtained with Stripe.js
cu.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
cu.description = "Customer for test@example.com"
cu.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$cu->description = "Customer for test@example.com";
$cu->source = "tok_17YYPH2eZvKYlo2C8ZbpILPR"; // obtained with Stripe.js
$cu->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
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_7oGjJvWit3N9Ps", {
  description: "Customer for test@example.com"
}, function(err, customer) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := customer.Update(
      "cus_7oGjJvWit3N9Ps",
      &stripe.CustomerParams{Desc: "Customer for test@example.com"},
    )
 
{
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
#<Stripe::Customer id=cus_7oGjJvWit3N9Ps 0x00000a> JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
<Customer customer id=cus_7oGjJvWit3N9Ps at 0x00000a> JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
Stripe\Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
com.stripe.model.Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
{
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}
&stripe.Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Customer for test@example.com",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}

Delete a customer

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

Arguments

  • customer 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 returnsraisesraisesthrowsthrowsthrowsreturns 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});
customer.Del({CUSTOMER_ID})
 
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
cu.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
cu.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$cu->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
cu.delete();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.del(
  "cus_7oGjJvWit3N9Ps",
  function(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := customer.Del("cus_7oGjJvWit3N9Ps")
 
{
  "deleted": true,
  "id": "cus_7oGjJvWit3N9Ps"
}
#<Stripe::Object id=cus_7oGjJvWit3N9Ps 0x00000a> JSON: {
  "deleted": true,
  "id": "cus_7oGjJvWit3N9Ps"
}
<Object object id=cus_7oGjJvWit3N9Ps at 0x00000a> JSON: {
  "deleted": true,
  "id": "cus_7oGjJvWit3N9Ps"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "cus_7oGjJvWit3N9Ps"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "cus_7oGjJvWit3N9Ps"
}
{
  "deleted": true,
  "id": "cus_7oGjJvWit3N9Ps"
}
nil

List all customers

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

Arguments

  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • 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 arrayMapobjectmap 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 returnraiseraisethrowthrowthrowreturn an 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/customers
Stripe::Customer.all
stripe.Customer.all()
\Stripe\Customer::all();
Customer.all(Map<String, Object> options);
stripe.customers.list();
customer.List()
 
curl https://api.stripe.com/v1/customers?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("limit", 3);

Customer.all(customerParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.list(
  { limit: 3 },
  function(err, customers) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CustomerListParams{}
params.Filters.AddFilter("limit", "", "3")
i := customer.List(params)
for i.Next() {
  c := i.Customer()
}
 
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    #<Stripe::Customer id=cus_7oGjJvWit3N9Ps 0x00000a> JSON: {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    },
    #<Stripe::Customer[...] ...>,
    #<Stripe::Customer[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers",
  has_more: false,
  data: [
    <Customer customer id=cus_7oGjJvWit3N9Ps at 0x00000a> JSON: {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    },
    <stripe.Customer[...] ...>,
    <stripe.Customer[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Customer JSON: {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    }
    [1] => <Stripe\Customer[...] ...>
    [2] => <Stripe\Customer[...] ...>
  ]
}
#<com.stripe.model.CustomerCollection id=#> JSON: {
  "data": [
    com.stripe.model.Customer JSON: {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    },
    #<com.stripe.model.Customer[...] ...>,
    #<com.stripe.model.Customer[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_7oGjJvWit3N9Ps",
      "object": "customer",
      "account_balance": 0,
      "created": 1454081404,
      "currency": "usd",
      "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
      "delinquent": false,
      "description": "Bob Jones",
      "discount": null,
      "email": null,
      "livemode": false,
      "metadata": {
      },
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [
          {
            "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
            "object": "card",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line1_check": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_zip_check": null,
            "brand": "Visa",
            "country": "US",
            "customer": "cus_7oGjJvWit3N9Ps",
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 4,
            "exp_year": 2040,
            "funding": "credit",
            "last4": "4242",
            "metadata": {
            },
            "name": null,
            "tokenization_method": null
          }
        ],
        "has_more": false,
        "total_count": 1,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
      }
    },
    {...},
    {...}
  ]
}
&stripe.Customer JSON: {
  "id": "cus_7oGjJvWit3N9Ps",
  "object": "customer",
  "account_balance": 0,
  "created": 1454081404,
  "currency": "usd",
  "default_source": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
  "delinquent": false,
  "description": "Bob Jones",
  "discount": null,
  "email": null,
  "livemode": false,
  "metadata": {
  },
  "shipping": null,
  "sources": {
    "object": "list",
    "data": [
      {
        "id": "card_17YeCF2eZvKYlo2CAr7Zy9w2",
        "object": "card",
        "address_city": null,
        "address_country": null,
        "address_line1": null,
        "address_line1_check": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": null,
        "brand": "Visa",
        "country": "US",
        "customer": "cus_7oGjJvWit3N9Ps",
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 4,
        "exp_year": 2040,
        "funding": "credit",
        "last4": "4242",
        "metadata": {
        },
        "name": null,
        "tokenization_method": null
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources"
  },
  "subscriptions": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions"
  }
}

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

  • id string

  • object string , value is "dispute"

  • 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).

  • balance_transactions array, contains: balance_transaction object

    List of zero, one, or two balance transactions that show funds withdrawn and reinstated to your Stripe account as a result of this dispute.

  • charge string

    ID of the charge that was disputed

  • created timestamp

    Date dispute was opened

  • currency currency

    Three-letter ISO currency code representing the currency of the amount that was disputed.

  • evidence hash, dispute_evidence object

    Evidence provided to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review.

  • evidence_details hash

    Information about the evidence submission.

    child attributes

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

    • has_evidence boolean

      Whether or not evidence has been saved for this dispute.

    • past_due boolean

      Whether or not the last evidence submission was submitted past the due date. Defaults to false if no evidence submissions have occurred. If true, then delivery of the latest evidence is not guaranteed.

    • submission_count integer

      The number of times the evidence has been submitted. You may submit evidence a maximum of 5 times.

  • is_charge_refundable boolean

    If true, it is still possible to refund the disputed payment. Once the payment has been fully refunded, no further funds will be withdrawn from your Stripe account as a result of this dispute.

  • livemode boolean

  • metadata #

    A set of key/value pairs that you can attach to a dispute object. It can be useful for storing additional information about the dispute in a structured format.

  • reason string

    Reason given by cardholder for dispute. Possible values are duplicate, fraudulent, subscription_canceled, product_unacceptable, product_not_received, unrecognized, credit_not_processed, incorrect_account_details, insufficient_funds, bank_cannot_process, debit_not_authorized, general. Read more about dispute reasons.

  • status string

    Current status of dispute. Possible values are warning_needs_response, warning_under_review, warning_closed, needs_response, response_disabled, under_review, charge_refunded, won, lost. 

{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
#<Stripe::Dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
<Dispute dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB at 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
Stripe\Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
com.stripe.model.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
&stripe.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}

The dispute_evidence object

Attributes

  • access_activity_log string

    Any server or activity logs showing proof that the customer accessed or downloaded the purchased digital product. This information should include IP addresses, corresponding timestamps, and any detailed recorded activity.

  • billing_address string

    The billing addess provided by the customer.

  • cancellation_policy string

    (ID of a file upload) Your subscription cancellation policy, as shown to the customer.

  • cancellation_policy_disclosure string

    An explanation of how and when the customer was shown your refund policy prior to purchase.

  • cancellation_rebuttal string

    A justification for why the customer’s subscription was not canceled.

  • customer_communication string

    (ID of a file upload) Any communication with the customer that you feel is relevant to your case (for example emails proving that they received the product or service, or demonstrating their use of or satisfaction with the product or service).

  • customer_email_address string

    The email address of the customer.

  • customer_name string

    The name of the customer.

  • customer_purchase_ip string

    The IP address that the customer used when making the purchase.

  • customer_signature string

    (ID of a file upload) A relevant document or contract showing the customer’s signature.

  • duplicate_charge_documentation string

    (ID of a file upload) Documentation for the prior charge that can uniquely identify the charge, such as a receipt, shipping label, work order, etc. This document should be paired with a similar document from the disputed payment that proves the two payments are separate.

  • duplicate_charge_explanation string

    An explanation of the difference between the disputed charge and the prior charge that appears to be a duplicate.

  • duplicate_charge_id string

    The Stripe ID for the prior charge which appears to be a duplicate of the disputed charge.

  • product_description string

    A description of the product or service which was sold.

  • receipt string

    (ID of a file upload) Any receipt or message sent to the customer notifying them of the charge.

  • refund_policy string

    (ID of a file upload) Your refund policy, as shown to the customer.

  • refund_policy_disclosure string

    Documentation demonstrating that the customer was shown your refund policy prior to purchase.

  • refund_refusal_explanation string

    A justification for why the customer is not entitled to a refund.

  • service_date string

    The date on which the customer received or began receiving the purchased service, in a clear human-readable format.

  • service_documentation string

    (ID of a file upload) Documentation showing proof that a service was provided to the customer. This could include a copy of a signed contract, work order, or other form of written agreement.

  • shipping_address string

    The address to which a physical product was shipped. You should try to include as much complete address information as possible.

  • shipping_carrier string

    The delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, please separate them with commas.

  • shipping_date string

    The date on which a physical product began its route to the shipping address, in a clear human-readable format.

  • shipping_documentation string

    (ID of a file upload) Documentation showing proof that a product was shipped to the customer at the same address the customer provided to you. This could include a copy of the shipment receipt, shipping label, etc, and should show the full shipping address of the customer, if possible.

  • shipping_tracking_number string

    The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.

  • uncategorized_file string

    (ID of a file upload) Any additional evidence or statements.

  • uncategorized_text string

    Any additional evidence or statements. 

{
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
#<Stripe::Object 0x00000a> JSON: {
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
<Object object at 0x00000a> JSON: {
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
Stripe\Object JSON: {
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
com.stripe.model.Object JSON: {
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
{
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}
&stripe.Object JSON: {
  "access_activity_log": null,
  "billing_address": null,
  "cancellation_policy": null,
  "cancellation_policy_disclosure": null,
  "cancellation_rebuttal": null,
  "customer_communication": null,
  "customer_email_address": null,
  "customer_name": null,
  "customer_purchase_ip": null,
  "customer_signature": null,
  "duplicate_charge_documentation": null,
  "duplicate_charge_explanation": null,
  "duplicate_charge_id": null,
  "product_description": null,
  "receipt": null,
  "refund_policy": null,
  "refund_policy_disclosure": null,
  "refund_refusal_explanation": null,
  "service_date": null,
  "service_documentation": null,
  "shipping_address": null,
  "shipping_carrier": null,
  "shipping_date": null,
  "shipping_documentation": null,
  "shipping_tracking_number": null,
  "uncategorized_file": null,
  "uncategorized_text": null
}

Retrieve a dispute

Retrieves the dispute with the given ID.

Arguments

  • dispute required

    ID of dispute to retrieve.

Returns

Returns a dispute if a valid dispute ID was provided. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error otherwise.

curl https://api.stripe.com/v1/disputes/dp_17Vv962eZvKYlo2CU7XhGGzB \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Dispute::retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.disputes.retrieve(
  "dp_17Vv962eZvKYlo2CU7XhGGzB",
  function(err, dispute) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

d, err := dispute.Get("dp_17Vv962eZvKYlo2CU7XhGGzB", nil)
 
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
#<Stripe::Dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
<Dispute dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB at 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
Stripe\Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
com.stripe.model.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
&stripe.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}

Update a dispute

When you get a dispute, contacting your customer is always the best first step. If that doesn’t work, you can submit 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.

Depending on your dispute type, different evidence fields will give you a better chance of winning your dispute. You may want to consult our guide to dispute types to help you figure out which evidence fields to provide.

Arguments

  • dispute required

    ID of the dispute to update.

  • evidence optional

    Evidence to upload to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review.

  • metadata optional

    A set of key/value pairs that you can attach to a dispute object. It can be useful for storing additional information about the dispute in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

Returns

Returns the dispute object.

POST https://api.stripe.com/v1/disputes/{DISPUTE_ID}
dispute = Stripe::Dispute.retrieve({DISPUTE_ID})
dispute.evidence => {NEW_EVIDENCE}
dispute.save
dispute = stripe.Dispute.retrieve({DISPUTE_ID})
dispute.evidence = {NEW_EVIDENCE}
dispute.save()
$dispute = \Stripe\Dispute::retrieve({DISPUTE_ID});
$dispute->evidence = {NEW_EVIDENCE};
$dispute->save();
Dispute dp = Dispute.retrieve({DISPUTE_ID});
Map<String, Object> disputeParams = new HashMap<String, Object>();
disputeParams.put("evidence", {NEW_EVIDENCE});
dp.update(disputeParams);
stripe.disputes.update({DISPUTE_ID}, {
  evidence: {NEW_EVIDENCE}
});
dispute.Update({DISPUTE_ID}, &stripe.DisputeParams{Evidence: {NEW_EVIDENCE}})
 
curl https://api.stripe.com/v1/disputes/dp_17Vv962eZvKYlo2CU7XhGGzB \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d evidence[customer_name]="Jane Austen" \
   -d evidence[product_description]="Lorem ipsum dolor sit amet." \
   -d evidence[shipping_documentation]=fil_15A3Gj2eZvKYlo2C0NxXGm4s

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

dispute = Stripe::Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
dispute.evidence = {
    :customer_name => "Jane Austen",
    :product_description => "Lorem ipsum dolor sit amet.",
    :shipping_documentation => "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  }
dispute.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

dispute = stripe.Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
dispute.evidence = {
    "customer_name": 'Jane Austen',
    "product_description": 'Lorem ipsum dolor sit amet.',
    "shipping_documentation": 'fil_15A3Gj2eZvKYlo2C0NxXGm4s'
  }
dispute.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$dp = \Stripe\Dispute::retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
$dp->evidence = array(
    "customer_name" => "Jane Austen",
    "product_description" => "Lorem ipsum dolor sit amet.",
    "shipping_documentation" => "fil_15A3Gj2eZvKYlo2C0NxXGm4s"
  );
$dp->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Dispute dp = Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
Map<String, Object> params = new HashMap<String, Object>();
Map<String, Object> evidence = new HashMap<String, Object>();
evidence.put("customer_name", "Jane Austen")
evidence.put("product_description", "Lorem ipsum dolor sit amet.")
evidence.put("shipping_documentation", "fil_15A3Gj2eZvKYlo2C0NxXGm4s")
params.put("evidence", evidence)
dp.update(params)
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.disputes.update(
  "dp_17Vv962eZvKYlo2CU7XhGGzB",
  {
    evidence: {
      customer_name: 'Jane Austen',
      product_description: 'Lorem ipsum dolor sit amet.',
      shipping_documentation: 'fil_15A3Gj2eZvKYlo2C0NxXGm4s'
    }
  },
  function(err, dispute) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

d, err := dispute.Update(
  "dp_17Vv962eZvKYlo2CU7XhGGzB",
  &stripe.DisputeParams{
    Evidence: &stripe.DisputeEvidenceParams{
      CustomerName: "Jane Austen",
      ProductDesc: "Lorem ipsum dolor sit amet.",
      ShippingDoc: "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
    },
  },
)
 
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
#<Stripe::Dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
<Dispute dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB at 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
Stripe\Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
com.stripe.model.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}
&stripe.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "product_description": "Lorem ipsum dolor sit amet",
    "customer_name": "Jane Austen",
    "customer_email_address": null,
    "billing_address": null,
    "customer_purchase_ip": null,
    "shipping_address": null,
    "shipping_date": null,
    "shipping_carrier": null,
    "shipping_tracking_number": null,
    "service_date": null,
    "access_activity_log": null,
    "duplicate_charge_id": null,
    "duplicate_charge_explanation": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "uncategorized_text": null,
    "customer_signature": null,
    "receipt": null,
    "shipping_documentation": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
    "service_documentation": null,
    "duplicate_charge_documentation": null,
    "refund_policy": null,
    "cancellation_policy": null,
    "customer_communication": null,
    "uncategorized_file": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}

Close 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 needs_response to lost. Closing a dispute is irreversible.

Arguments

  • dispute required

    ID of dispute to close.

Returns

Returns the dispute object.

POST https://api.stripe.com/v1/disputes/{DISPUTE_ID}/close
dispute = Stripe::Dispute.retrieve({DISPUTE_ID})
dispute.close
dispute = stripe.Dispute.retrieve({DISPUTE_ID})
dispute.close()
$dispute = \Stripe\Dispute::retrieve({DISPUTE_ID});
$dispute.close();
Dispute dp = Dispute.retrieve({DISPUTE_ID});
dp.close();
stripe.disputes.close({DISPUTE_ID});
dispute.Close({DISPUTE_ID})
 
curl https://api.stripe.com/v1/disputes/dp_17Vv962eZvKYlo2CU7XhGGzB/close \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

dispute = Stripe::Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
dispute.close
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

dispute = stripe.Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB")
dispute.close()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$dp = \Stripe\Dispute::retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
$dp->close();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Dispute dp = Dispute.retrieve("dp_17Vv962eZvKYlo2CU7XhGGzB");
dp.close()
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.disputes.close(
  "dp_17Vv962eZvKYlo2CU7XhGGzB",
  function(err, dispute) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

d, err := dispute.Close("dp_17Vv962eZvKYlo2CU7XhGGzB")
 
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
#<Stripe::Dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
<Dispute dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB at 0x00000a> JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
Stripe\Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
com.stripe.model.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
{
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}
&stripe.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "lost"
}

List all disputes

Returns a list of your disputes.

Arguments

  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • 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 arrayMapobjectmap with a data property that contains an array of up to limit disputes, starting after dispute starting_after. Each entry in the array is a separate dispute object. If no more disputes are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrowreturn an an error.

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

GET https://api.stripe.com/v1/disputes
Stripe::Dispute.all
stripe.Dispute.all()
\Stripe\Dispute::all();
Dispute.all(Map<String, Object> options);
stripe.disputes.list();
dispute.List()
 
curl https://api.stripe.com/v1/disputes?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Dispute.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Dispute.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Dispute::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> disputeParams = new HashMap<String, Object>();
disputeParams.put("limit", 3);

Dispute.all(disputeParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.disputes.list(
  { limit: 3 },
  function(err, disputes) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.DisputeListParams{}
params.Filters.AddFilter("limit", "", "3")
i := dispute.List(params)
for i.Next() {
  d := i.Dispute()
}
 
{
  "object": "list",
  "url": "/v1/disputes",
  "has_more": false,
  "data": [
    {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "pending",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/disputes",
  "has_more": false,
  "data": [
    #<Stripe::Dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB 0x00000a> JSON: {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "pending",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    },
    #<Stripe::Dispute[...] ...>,
    #<Stripe::Dispute[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/disputes",
  has_more: false,
  data: [
    <Dispute dispute id=dp_17Vv962eZvKYlo2CU7XhGGzB at 0x00000a> JSON: {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "pending",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    },
    <stripe.Dispute[...] ...>,
    <stripe.Dispute[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/disputes",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Dispute JSON: {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "pending",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    }
    [1] => <Stripe\Dispute[...] ...>
    [2] => <Stripe\Dispute[...] ...>
  ]
}
#<com.stripe.model.DisputeCollection id=#> JSON: {
  "data": [
    com.stripe.model.Dispute JSON: {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "pending",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    },
    #<com.stripe.model.Dispute[...] ...>,
    #<com.stripe.model.Dispute[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/disputes",
  "has_more": false,
  "data": [
    {
      "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "object": "dispute",
      "amount": 100,
      "balance_transactions": [
        {
          "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
          "object": "balance_transaction",
          "amount": -100,
          "available_on": 1454025600,
          "created": 1453431572,
          "currency": "usd",
          "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
          "fee": 1500,
          "fee_details": [
            {
              "amount": 1500,
              "application": null,
              "currency": "usd",
              "description": "Dispute fee",
              "type": "stripe_fee"
            }
          ],
          "net": -1600,
          "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
          "sourced_transfers": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
          },
          "status": "pending",
          "type": "adjustment"
        }
      ],
      "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
      "created": 1453431572,
      "currency": "usd",
      "evidence": {
        "access_activity_log": null,
        "billing_address": null,
        "cancellation_policy": null,
        "cancellation_policy_disclosure": null,
        "cancellation_rebuttal": null,
        "customer_communication": null,
        "customer_email_address": null,
        "customer_name": null,
        "customer_purchase_ip": null,
        "customer_signature": null,
        "duplicate_charge_documentation": null,
        "duplicate_charge_explanation": null,
        "duplicate_charge_id": null,
        "product_description": null,
        "receipt": null,
        "refund_policy": null,
        "refund_policy_disclosure": null,
        "refund_refusal_explanation": null,
        "service_date": null,
        "service_documentation": null,
        "shipping_address": null,
        "shipping_carrier": null,
        "shipping_date": null,
        "shipping_documentation": null,
        "shipping_tracking_number": null,
        "uncategorized_file": null,
        "uncategorized_text": null
      },
      "evidence_details": {
        "due_by": 1454889599,
        "has_evidence": false,
        "past_due": false,
        "submission_count": 0
      },
      "is_charge_refundable": false,
      "livemode": false,
      "metadata": {
      },
      "reason": "general",
      "status": "needs_response"
    },
    {...},
    {...}
  ]
}
&stripe.Dispute JSON: {
  "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
  "object": "dispute",
  "amount": 100,
  "balance_transactions": [
    {
      "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
      "object": "balance_transaction",
      "amount": -100,
      "available_on": 1454025600,
      "created": 1453431572,
      "currency": "usd",
      "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
      "fee": 1500,
      "fee_details": [
        {
          "amount": 1500,
          "application": null,
          "currency": "usd",
          "description": "Dispute fee",
          "type": "stripe_fee"
        }
      ],
      "net": -1600,
      "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
      "sourced_transfers": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
      },
      "status": "pending",
      "type": "adjustment"
    }
  ],
  "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
  "created": 1453431572,
  "currency": "usd",
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy": null,
    "cancellation_policy_disclosure": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email_address": null,
    "customer_name": null,
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": null,
    "duplicate_charge_id": null,
    "product_description": null,
    "receipt": null,
    "refund_policy": null,
    "refund_policy_disclosure": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": null,
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": null,
    "uncategorized_file": null,
    "uncategorized_text": null
  },
  "evidence_details": {
    "due_by": 1454889599,
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {
  },
  "reason": "general",
  "status": "needs_response"
}

Events

Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new Event object. For example, when a charge succeeds, we create a charge.succeeded event; When an invoice payment attempt fails, we create an invoice.payment_failed event. Note that many API requests may cause multiple events to be created. For example, if you create a new subscription for a customer, you will receive both a customer.subscription.created event and a charge.succeeded event.

Like our other API resources, you can retrieve an individual event or a list of events from the API. We also have a system for sending the events directly to your server, called webhooks. Webhooks are managed in your account settings, and our webhook guide will help you get set up.

When using Connect, you can also receive notifications of events that occur in connected accounts. For these events, there will be an additional user_id attribute in the received Event object.

NOTE: Right now, we only guarantee access to events through the Retrieve Event API for 30 days.

The event object

Attributes

  • id string

  • object string , value is "event"

  • api_version string

    The Stripe API version used to render data. Note: this property is populated for events on or after October 31, 2014.

  • created timestamp

  • data hash

    Hash containing data associated with the event.

    child attributes

    • object hash

      describes the object the event is about. For example, an invoice.created event will have a full invoice object as the value of the object key.

    • previous_attributes hash

      Hash containing the names of the attributes that have changed and their previous values (only sent along with *.updated events)

  • livemode boolean

  • pending_webhooks positive integer or zero

    Number of webhooks yet to be delivered successfully (return a 20x response) to the URLs you’ve specified.

  • request string

    ID of the API request that caused the event. If null, the event was automatic (e.g. Stripe’s automatic subscription handling). Request logs are available in the dashboard but currently not in the API. Note: this property is populated for events on or after April 23, 2013.

  • type string

    Description of the event: e.g. invoice.created, charge.refunded, etc. 

{
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
#<Stripe::Event id=evt_17YeVf2eZvKYlo2Ck0eHQczk 0x00000a> JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
<Event event id=evt_17YeVf2eZvKYlo2Ck0eHQczk at 0x00000a> JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
Stripe\Event JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
com.stripe.model.Event JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
{
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
&stripe.Event JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}

Retrieve an event

Retrieves the details of an event. Supply the unique identifier of the event, which you might have received in a webhook.

Arguments

  • id required

    The identifier of the event to be retrieved.

Returns

Returns an event object if a valid identifier was provided. All events share a common structure, detailed to the right. The only property that will differ is the data property.

In each case, the data dictionaryhashdictionaryassociative arrayMapobjectmap will have an attribute called object and its value will be the same as retrieving the same object directly from the API. For example, a customer.created event will have the same information as retrieving the relevant customer would.

In cases where the attributes of an object have changed, data will also contain a dictionaryhashdictionaryassociative arrayMapobjectmap containing the changes.

curl https://api.stripe.com/v1/events/evt_17YeVf2eZvKYlo2Ck0eHQczk \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Event.retrieve("evt_17YeVf2eZvKYlo2Ck0eHQczk")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Event.retrieve("evt_17YeVf2eZvKYlo2Ck0eHQczk")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Event::retrieve("evt_17YeVf2eZvKYlo2Ck0eHQczk");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Event.retrieve("evt_17YeVf2eZvKYlo2Ck0eHQczk");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.events.retrieve(
  "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  function(err, event) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

e, err := event.Get("evt_17YeVf2eZvKYlo2Ck0eHQczk")
 
{
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
#<Stripe::Event id=evt_17YeVf2eZvKYlo2Ck0eHQczk 0x00000a> JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
<Event event id=evt_17YeVf2eZvKYlo2Ck0eHQczk at 0x00000a> JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
Stripe\Event JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
com.stripe.model.Event JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
{
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}
&stripe.Event JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}

List all events

List events, going back up to 30 days.

Arguments

  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

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

  • type optional

    A string containing a specific event name, or group of events using * as a wildcard. The list will be filtered to include only events with a matching event property

Returns

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

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

GET https://api.stripe.com/v1/events
Stripe::Event.all
stripe.Event.all()
\Stripe\Event::all();
Event.all(Map<String, Object> options);
stripe.events.list();
event.List()
 
curl https://api.stripe.com/v1/events?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Event.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Event.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Event::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> eventParams = new HashMap<String, Object>();
eventParams.put("limit", 3);

Event.all(eventParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.events.list(
  { limit: 3 },
  function(err, events) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.EventListParams{}
params.Filters.AddFilter("limit", "", "3")
i := event.List(params)
for i.Next() {
  e := i.Event()
}
 
{
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": [
    {
      "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
      "object": "event",
      "api_version": "2015-10-16",
      "created": 1454082607,
      "data": {
        "object": {
          "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
          "object": "charge",
          "amount": 5001,
          "amount_refunded": 0,
          "application_fee": null,
          "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
          "captured": true,
          "created": 1454082607,
          "currency": "usd",
          "customer": null,
          "description": "User: 590. Events: 966. Total Tickets: 1.",
          "destination": null,
          "dispute": null,
          "failure_code": null,
          "failure_message": null,
          "fraud_details": {
          },
          "invoice": null,
          "livemode": false,
          "metadata": {
            "user_id": "590",
            "seller_id": "797",
            "events": "PHPUNIT Demo",
            "event_ids": "966"
          },
          "order": null,
          "paid": true,
          "receipt_email": null,
          "receipt_number": null,
          "refunded": false,
          "refunds": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
          },
          "shipping": null,
          "source": {
            "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
            "object": "card",
            "address_city": "Pittsburgh",
            "address_country": "US",
            "address_line1": "414 Grant St",
            "address_line1_check": "pass",
            "address_line2": null,
            "address_state": "PA",
            "address_zip": "15219",
            "address_zip_check": "pass",
            "brand": "Visa",
            "country": "US",
            "customer": null,
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2022,
            "fingerprint": "tiDP36QdYA6X7km8",
            "funding": "unknown",
            "last4": "1111",
            "metadata": {
            },
            "name": "Harold Hamburger",
            "tokenization_method": null
          },
          "statement_descriptor": null,
          "status": "succeeded"
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": "req_7oH3U54igUjkeQ",
      "type": "charge.succeeded"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": [
    #<Stripe::Event id=evt_17YeVf2eZvKYlo2Ck0eHQczk 0x00000a> JSON: {
      "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
      "object": "event",
      "api_version": "2015-10-16",
      "created": 1454082607,
      "data": {
        "object": {
          "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
          "object": "charge",
          "amount": 5001,
          "amount_refunded": 0,
          "application_fee": null,
          "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
          "captured": true,
          "created": 1454082607,
          "currency": "usd",
          "customer": null,
          "description": "User: 590. Events: 966. Total Tickets: 1.",
          "destination": null,
          "dispute": null,
          "failure_code": null,
          "failure_message": null,
          "fraud_details": {
          },
          "invoice": null,
          "livemode": false,
          "metadata": {
            "user_id": "590",
            "seller_id": "797",
            "events": "PHPUNIT Demo",
            "event_ids": "966"
          },
          "order": null,
          "paid": true,
          "receipt_email": null,
          "receipt_number": null,
          "refunded": false,
          "refunds": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
          },
          "shipping": null,
          "source": {
            "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
            "object": "card",
            "address_city": "Pittsburgh",
            "address_country": "US",
            "address_line1": "414 Grant St",
            "address_line1_check": "pass",
            "address_line2": null,
            "address_state": "PA",
            "address_zip": "15219",
            "address_zip_check": "pass",
            "brand": "Visa",
            "country": "US",
            "customer": null,
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2022,
            "fingerprint": "tiDP36QdYA6X7km8",
            "funding": "unknown",
            "last4": "1111",
            "metadata": {
            },
            "name": "Harold Hamburger",
            "tokenization_method": null
          },
          "statement_descriptor": null,
          "status": "succeeded"
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": "req_7oH3U54igUjkeQ",
      "type": "charge.succeeded"
    },
    #<Stripe::Event[...] ...>,
    #<Stripe::Event[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/events",
  has_more: false,
  data: [
    <Event event id=evt_17YeVf2eZvKYlo2Ck0eHQczk at 0x00000a> JSON: {
      "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
      "object": "event",
      "api_version": "2015-10-16",
      "created": 1454082607,
      "data": {
        "object": {
          "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
          "object": "charge",
          "amount": 5001,
          "amount_refunded": 0,
          "application_fee": null,
          "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
          "captured": true,
          "created": 1454082607,
          "currency": "usd",
          "customer": null,
          "description": "User: 590. Events: 966. Total Tickets: 1.",
          "destination": null,
          "dispute": null,
          "failure_code": null,
          "failure_message": null,
          "fraud_details": {
          },
          "invoice": null,
          "livemode": false,
          "metadata": {
            "user_id": "590",
            "seller_id": "797",
            "events": "PHPUNIT Demo",
            "event_ids": "966"
          },
          "order": null,
          "paid": true,
          "receipt_email": null,
          "receipt_number": null,
          "refunded": false,
          "refunds": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
          },
          "shipping": null,
          "source": {
            "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
            "object": "card",
            "address_city": "Pittsburgh",
            "address_country": "US",
            "address_line1": "414 Grant St",
            "address_line1_check": "pass",
            "address_line2": null,
            "address_state": "PA",
            "address_zip": "15219",
            "address_zip_check": "pass",
            "brand": "Visa",
            "country": "US",
            "customer": null,
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2022,
            "fingerprint": "tiDP36QdYA6X7km8",
            "funding": "unknown",
            "last4": "1111",
            "metadata": {
            },
            "name": "Harold Hamburger",
            "tokenization_method": null
          },
          "statement_descriptor": null,
          "status": "succeeded"
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": "req_7oH3U54igUjkeQ",
      "type": "charge.succeeded"
    },
    <stripe.Event[...] ...>,
    <stripe.Event[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/events",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Event JSON: {
      "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
      "object": "event",
      "api_version": "2015-10-16",
      "created": 1454082607,
      "data": {
        "object": {
          "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
          "object": "charge",
          "amount": 5001,
          "amount_refunded": 0,
          "application_fee": null,
          "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
          "captured": true,
          "created": 1454082607,
          "currency": "usd",
          "customer": null,
          "description": "User: 590. Events: 966. Total Tickets: 1.",
          "destination": null,
          "dispute": null,
          "failure_code": null,
          "failure_message": null,
          "fraud_details": {
          },
          "invoice": null,
          "livemode": false,
          "metadata": {
            "user_id": "590",
            "seller_id": "797",
            "events": "PHPUNIT Demo",
            "event_ids": "966"
          },
          "order": null,
          "paid": true,
          "receipt_email": null,
          "receipt_number": null,
          "refunded": false,
          "refunds": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
          },
          "shipping": null,
          "source": {
            "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
            "object": "card",
            "address_city": "Pittsburgh",
            "address_country": "US",
            "address_line1": "414 Grant St",
            "address_line1_check": "pass",
            "address_line2": null,
            "address_state": "PA",
            "address_zip": "15219",
            "address_zip_check": "pass",
            "brand": "Visa",
            "country": "US",
            "customer": null,
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2022,
            "fingerprint": "tiDP36QdYA6X7km8",
            "funding": "unknown",
            "last4": "1111",
            "metadata": {
            },
            "name": "Harold Hamburger",
            "tokenization_method": null
          },
          "statement_descriptor": null,
          "status": "succeeded"
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": "req_7oH3U54igUjkeQ",
      "type": "charge.succeeded"
    }
    [1] => <Stripe\Event[...] ...>
    [2] => <Stripe\Event[...] ...>
  ]
}
#<com.stripe.model.EventCollection id=#> JSON: {
  "data": [
    com.stripe.model.Event JSON: {
      "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
      "object": "event",
      "api_version": "2015-10-16",
      "created": 1454082607,
      "data": {
        "object": {
          "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
          "object": "charge",
          "amount": 5001,
          "amount_refunded": 0,
          "application_fee": null,
          "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
          "captured": true,
          "created": 1454082607,
          "currency": "usd",
          "customer": null,
          "description": "User: 590. Events: 966. Total Tickets: 1.",
          "destination": null,
          "dispute": null,
          "failure_code": null,
          "failure_message": null,
          "fraud_details": {
          },
          "invoice": null,
          "livemode": false,
          "metadata": {
            "user_id": "590",
            "seller_id": "797",
            "events": "PHPUNIT Demo",
            "event_ids": "966"
          },
          "order": null,
          "paid": true,
          "receipt_email": null,
          "receipt_number": null,
          "refunded": false,
          "refunds": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
          },
          "shipping": null,
          "source": {
            "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
            "object": "card",
            "address_city": "Pittsburgh",
            "address_country": "US",
            "address_line1": "414 Grant St",
            "address_line1_check": "pass",
            "address_line2": null,
            "address_state": "PA",
            "address_zip": "15219",
            "address_zip_check": "pass",
            "brand": "Visa",
            "country": "US",
            "customer": null,
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2022,
            "fingerprint": "tiDP36QdYA6X7km8",
            "funding": "unknown",
            "last4": "1111",
            "metadata": {
            },
            "name": "Harold Hamburger",
            "tokenization_method": null
          },
          "statement_descriptor": null,
          "status": "succeeded"
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": "req_7oH3U54igUjkeQ",
      "type": "charge.succeeded"
    },
    #<com.stripe.model.Event[...] ...>,
    #<com.stripe.model.Event[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": [
    {
      "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
      "object": "event",
      "api_version": "2015-10-16",
      "created": 1454082607,
      "data": {
        "object": {
          "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
          "object": "charge",
          "amount": 5001,
          "amount_refunded": 0,
          "application_fee": null,
          "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
          "captured": true,
          "created": 1454082607,
          "currency": "usd",
          "customer": null,
          "description": "User: 590. Events: 966. Total Tickets: 1.",
          "destination": null,
          "dispute": null,
          "failure_code": null,
          "failure_message": null,
          "fraud_details": {
          },
          "invoice": null,
          "livemode": false,
          "metadata": {
            "user_id": "590",
            "seller_id": "797",
            "events": "PHPUNIT Demo",
            "event_ids": "966"
          },
          "order": null,
          "paid": true,
          "receipt_email": null,
          "receipt_number": null,
          "refunded": false,
          "refunds": {
            "object": "list",
            "data": [
    
            ],
            "has_more": false,
            "total_count": 0,
            "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
          },
          "shipping": null,
          "source": {
            "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
            "object": "card",
            "address_city": "Pittsburgh",
            "address_country": "US",
            "address_line1": "414 Grant St",
            "address_line1_check": "pass",
            "address_line2": null,
            "address_state": "PA",
            "address_zip": "15219",
            "address_zip_check": "pass",
            "brand": "Visa",
            "country": "US",
            "customer": null,
            "cvc_check": "pass",
            "dynamic_last4": null,
            "exp_month": 12,
            "exp_year": 2022,
            "fingerprint": "tiDP36QdYA6X7km8",
            "funding": "unknown",
            "last4": "1111",
            "metadata": {
            },
            "name": "Harold Hamburger",
            "tokenization_method": null
          },
          "statement_descriptor": null,
          "status": "succeeded"
        }
      },
      "livemode": false,
      "pending_webhooks": 0,
      "request": "req_7oH3U54igUjkeQ",
      "type": "charge.succeeded"
    },
    {...},
    {...}
  ]
}
&stripe.Event JSON: {
  "id": "evt_17YeVf2eZvKYlo2Ck0eHQczk",
  "object": "event",
  "api_version": "2015-10-16",
  "created": 1454082607,
  "data": {
    "object": {
      "id": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "object": "charge",
      "amount": 5001,
      "amount_refunded": 0,
      "application_fee": null,
      "balance_transaction": "txn_17YeVf2eZvKYlo2CWVYIvl3Z",
      "captured": true,
      "created": 1454082607,
      "currency": "usd",
      "customer": null,
      "description": "User: 590. Events: 966. Total Tickets: 1.",
      "destination": null,
      "dispute": null,
      "failure_code": null,
      "failure_message": null,
      "fraud_details": {
      },
      "invoice": null,
      "livemode": false,
      "metadata": {
        "user_id": "590",
        "seller_id": "797",
        "events": "PHPUNIT Demo",
        "event_ids": "966"
      },
      "order": null,
      "paid": true,
      "receipt_email": null,
      "receipt_number": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [

        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/charges/ch_17YeVf2eZvKYlo2CbSkw0Av7/refunds"
      },
      "shipping": null,
      "source": {
        "id": "card_17YeVf2eZvKYlo2CP9r7yjMm",
        "object": "card",
        "address_city": "Pittsburgh",
        "address_country": "US",
        "address_line1": "414 Grant St",
        "address_line1_check": "pass",
        "address_line2": null,
        "address_state": "PA",
        "address_zip": "15219",
        "address_zip_check": "pass",
        "brand": "Visa",
        "country": "US",
        "customer": null,
        "cvc_check": "pass",
        "dynamic_last4": null,
        "exp_month": 12,
        "exp_year": 2022,
        "fingerprint": "tiDP36QdYA6X7km8",
        "funding": "unknown",
        "last4": "1111",
        "metadata": {
        },
        "name": "Harold Hamburger",
        "tokenization_method": null
      },
      "statement_descriptor": null,
      "status": "succeeded"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": "req_7oH3U54igUjkeQ",
  "type": "charge.succeeded"
}

Types of events

This is a list of all the types of events we currently send. We may add more at any time, so you shouldn't rely on only these types existing in your code.

You'll notice that these events follow a pattern: resource.event. Our goal is to design a consistent system that makes things easier to anticipate and code against. NOTE: Events that occur on "sub" resources like customer.subscription do not trigger the parent's update event.

Event

  • account.updated describes an account

    Occurs whenever an account status or property has changed.

  • account.application.deauthorized describes an application

    Occurs whenever a user deauthorizes an application. Sent to the related application only.

    child parameters

    • id string

    • object string, value is "application"

    • name string

      The name of the Connect application.

  • account.external_account.created describes an external account (e.g., card or bank account)

    Occurs whenever an external account is created.

  • account.external_account.deleted describes an external account (e.g., card or bank account)

    Occurs whenever an external account is deleted.

  • account.external_account.updated describes an external account (e.g., card or bank account)

    Occurs whenever an external account is updated.

  • application_fee.created describes an application fee

    Occurs whenever an application fee is created on a charge.

  • application_fee.refunded describes an application fee

    Occurs whenever an application fee is refunded, whether from refunding a charge or from refunding the application fee directly, including partial refunds.

  • application_fee.refund.updated describes a fee refund

    Occurs whenever an application fee refund is updated.

  • balance.available describes a balance

    Occurs whenever your Stripe balance has been updated (e.g. when a charge collected is available to be paid out). By default, Stripe will automatically transfer any funds in your balance to your bank account on a daily basis.

  • bitcoin.receiver.created describes a bitcoin receiver

    Occurs whenever a receiver has been created.

  • bitcoin.receiver.filled describes a bitcoin receiver

    Occurs whenever a receiver is filled (that is, when it has received enough bitcoin to process a payment of the same amount).

  • bitcoin.receiver.updated describes a bitcoin receiver

    Occurs whenever a receiver is updated.

  • bitcoin.receiver.transaction.created describes a bitcoin receiver

    Occurs whenever bitcoin is pushed to a receiver.

  • charge.captured describes a charge

    Occurs whenever a previously uncaptured charge is captured.

  • charge.failed describes a charge

    Occurs whenever a failed charge attempt occurs.

  • charge.refunded describes a charge

    Occurs whenever a charge is refunded, including partial refunds.

  • charge.succeeded describes a charge

    Occurs whenever a new charge is created and is successful.

  • charge.updated describes a charge

    Occurs whenever a charge description or metadata is updated.

  • charge.dispute.closed describes a dispute

    Occurs when the dispute is closed and the dispute status changes to charge_refunded, lost, warning_closed, or won.

  • charge.dispute.created describes a dispute

    Occurs whenever a customer disputes a charge with their bank (chargeback).

  • charge.dispute.funds_reinstated describes a dispute

    Occurs when funds are reinstated to your account after a dispute is won.

  • charge.dispute.funds_withdrawn describes a dispute

    Occurs when funds are removed from your account due to a dispute.

  • charge.dispute.updated describes a dispute

    Occurs when the dispute is updated (usually with evidence).

  • coupon.created describes a coupon

    Occurs whenever a coupon is created.

  • coupon.deleted describes a coupon

    Occurs whenever a coupon is deleted.

  • coupon.updated describes a coupon

    Occurs whenever a coupon is updated.

  • customer.created describes a customer

    Occurs whenever a new customer is created.

  • customer.deleted describes a customer

    Occurs whenever a customer is deleted.

  • customer.updated describes a customer

    Occurs whenever any property of a customer changes.

  • customer.discount.created describes a discount

    Occurs whenever a coupon is attached to a customer.

  • customer.discount.deleted describes a discount

    Occurs whenever a customer's discount is removed.

  • customer.discount.updated describes a discount

    Occurs whenever a customer is switched from one coupon to another.

  • customer.source.created describes a source (e.g., card or Bitcoin receiver)

    Occurs whenever a new source is created for the customer.

  • customer.source.deleted describes a source (e.g., card or Bitcoin receiver)

    Occurs whenever a source is removed from a customer.

  • customer.source.updated describes a source (e.g., card or Bitcoin receiver)

    Occurs whenever a source's details are changed.

  • customer.subscription.created describes a subscription

    Occurs whenever a customer with no subscription is signed up for a plan.

  • customer.subscription.deleted describes a subscription

    Occurs whenever a customer ends their subscription.

  • customer.subscription.trial_will_end describes a subscription

    Occurs three days before the trial period of a subscription is scheduled to end.

  • customer.subscription.updated describes a subscription

    Occurs whenever a subscription changes. Examples would include switching from one plan to another, or switching status from trial to active.

  • invoice.created describes an invoice

    Occurs whenever a new invoice is created. If you are using webhooks, Stripe will wait one hour after they have all succeeded to attempt to pay the invoice; the only exception here is on the first invoice, which gets created and paid immediately when you subscribe a customer to a plan. If your webhooks do not all respond successfully, Stripe will continue retrying the webhooks every hour and will not attempt to pay the invoice. After 3 days, Stripe will attempt to pay the invoice regardless of whether or not your webhooks have succeeded. See how to respond to a webhook.

  • invoice.payment_failed describes an invoice

    Occurs whenever an invoice attempts to be paid, and the payment fails. This can occur either due to a declined payment, or because the customer has no active card. A particular case of note is that if a customer with no active card reaches the end of its free trial, an invoice.payment_failed notification will occur.

  • invoice.payment_succeeded describes an invoice

    Occurs whenever an invoice attempts to be paid, and the payment succeeds.

  • invoice.updated describes an invoice

    Occurs whenever an invoice changes (for example, the amount could change).

  • invoiceitem.created describes an invoiceitem

    Occurs whenever an invoice item is created.

  • invoiceitem.deleted describes an invoiceitem

    Occurs whenever an invoice item is deleted.

  • invoiceitem.updated describes an invoiceitem

    Occurs whenever an invoice item is updated.

  • order.created describes an order

    Occurs whenever an order is created.

  • order.payment_failed describes an order

    Occurs whenever payment is attempted on an order, and the payment fails.

  • order.payment_succeeded describes an order

    Occurs whenever payment is attempted on an order, and the payment succeeds.

  • order.updated describes an order

    Occurs whenever an order is updated.

  • plan.created describes a plan

    Occurs whenever a plan is created.

  • plan.deleted describes a plan

    Occurs whenever a plan is deleted.

  • plan.updated describes a plan

    Occurs whenever a plan is updated.

  • product.created describes a product

    Occurs whenever a product is created.

  • product.deleted describes a product

    Occurs whenever a product is deleted.

  • product.updated describes a product

    Occurs whenever a product is updated.

  • recipient.created describes a recipient

    Occurs whenever a recipient is created.

  • recipient.deleted describes a recipient

    Occurs whenever a recipient is deleted.

  • recipient.updated describes a recipient

    Occurs whenever a recipient is updated.

  • sku.created describes a sku

    Occurs whenever a SKU is created.

  • sku.deleted describes a sku

    Occurs whenever a SKU is deleted.

  • sku.updated describes a sku

    Occurs whenever a SKU is updated.

  • transfer.created describes a transfer

    Occurs whenever a new transfer is created.

  • transfer.failed describes a transfer

    Occurs whenever Stripe attempts to send a transfer and that transfer fails.

  • transfer.paid describes a transfer

    Occurs whenever a sent transfer is expected to be available in the destination bank account. If the transfer failed, a transfer.failed webhook will additionally be sent at a later time. Note to Connect users: this event is only created for transfers from your connected Stripe accounts to their bank accounts, not for transfers to the connected accounts themselves.

  • transfer.reversed describes a transfer

    Occurs whenever a transfer is reversed, including partial reversals.

  • transfer.updated describes a transfer

    Occurs whenever the description or metadata of a transfer is updated.

  • ping has no description

    May be sent by Stripe at any time to see if a provided webhook URL is working.

File Uploads

There are various times when you'll want to upload files to Stripe (for example, when uploading dispute evidence). This can be done by creating a file upload object. When you upload a file, the API responds with a file token and other information about the file. The token can then be used to retrieve a file object.

Note that to upload documents, the uploads API endpoint must be used: https://uploads.stripe.com.

For further documentation and examples, see the File Upload Guide.

The file_upload object

Attributes

  • id string

  • object string , value is "file_upload"

  • created timestamp

  • purpose string

    The purpose of the uploaded file. Possible values are identity_document, dispute_evidence, business_logo.

  • size integer

    The size in bytes of the file upload object.

  • type string

    The type of the file returned. Returns one of the following: pdf, jpg, png.

  • url string

    A read-only URL where the uploaded file can be accessed. Will be nil unless the uploaded file has one of the following purposes: dispute_evidence, business_logo. Also nil if retrieved with the publishable API key. 

{
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
#<Stripe::FileUpload id=fil_15A3Gj2eZvKYlo2C0NxXGm4s 0x00000a> JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
<FileUpload file_upload id=fil_15A3Gj2eZvKYlo2C0NxXGm4s at 0x00000a> JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
Stripe\FileUpload JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
com.stripe.model.FileUpload JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
{
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
&stripe.FileUpload JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}

Create a file upload

To upload a file to Stripe, you’ll need to send a request of type multipart/form-data. The request should contain the file you would like to upload, as well as the parameters for creating a file.

All of Stripe’s officially supported API libraries should have support for sending multipart/form-data.

Arguments

  • file required

    A file to upload. The file should follow the specifications of RFC 2388 (which defines file transfers for the multipart/form-data protocol).

  • purpose required

    The purpose of the uploaded file. Possible values are identity_document, dispute_evidence, business_logo.

Returns

Returns the file object.

POST https://uploads.stripe.com/v1/files
Stripe::FileUpload.create
stripe.FileUpload.create()
\Stripe\FileUpload::create();
FileUpload.create();
stripe.fileUploads.create();
fileupload.New()
 
curl https://uploads.stripe.com/v1/files \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -F purpose=dispute_evidence \
   -F file="@/path/to/a/file.jpg"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::FileUpload.create(
  :purpose => 'dispute_evidence',
  :file => File.new('/path/to/a/file.jpg')
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

fp = open('/path/to/a/file.jpg', 'r')
stripe.FileUpload.create(
  purpose='dispute_evidence',
  file=fp
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$fp = fopen('/path/to/a/file.jpg', 'r');
\Stripe\FileUpload::create(array(
  'purpose' => 'dispute_evidence',
  'file' => $fp
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> fileUploadParams = new HashMap<String, Object>();
fileUploadParams.put("purpose", dispute_evidence);
fileUploadParams.put("file", new File('/path/to/a/file.jpg'));

Fileupload.create(fileUploadParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

var fp = fs.readFileSync('/path/to/a/file.jpg');
stripe.fileUploads.create({
  purpose: 'dispute_evidence',
  file: {
    data: fp,
    name: 'file_name.jpg',
    type: 'application/octet-stream'
  }
}, function(err, fileUpload) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

fp, _ := os.Open("/path/to/a/file.jpg")
ch, err := fileupload.New(&FileUploadParams{
  Purpose: "dispute_evidence",
  File: fp,
})
 
{
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
#<Stripe::FileUpload id=fil_15A3Gj2eZvKYlo2C0NxXGm4s 0x00000a> JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
<FileUpload file_upload id=fil_15A3Gj2eZvKYlo2C0NxXGm4s at 0x00000a> JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
Stripe\FileUpload JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
com.stripe.model.FileUpload JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
{
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
&stripe.FileUpload JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}

Retrieve a file upload

Retrieves the details of an existing file object. Supply the unique file upload ID from a file creation request, and Stripe will return the corresponding transfer information.

Arguments

  • id required

    The identifier of the file upload to be retrieved.

Returns

Returns a file upload object if a valid identifier was provided, and returnsraisesraisesthrowsthrowsthrowsreturns an error otherwise.

curl https://uploads.stripe.com/v1/files/fil_15A3Gj2eZvKYlo2C0NxXGm4s \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::FileUpload.retrieve("fil_15A3Gj2eZvKYlo2C0NxXGm4s")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.FileUpload.retrieve("fil_15A3Gj2eZvKYlo2C0NxXGm4s")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\FileUpload::retrieve("fil_15A3Gj2eZvKYlo2C0NxXGm4s");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

FileUpload.retrieve("fil_15A3Gj2eZvKYlo2C0NxXGm4s");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.fileUploads.retrieve(
  "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  function(err, fileUpload) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

f, err := fileupload.Get("fil_15A3Gj2eZvKYlo2C0NxXGm4s", nil)
 
{
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
#<Stripe::FileUpload id=fil_15A3Gj2eZvKYlo2C0NxXGm4s 0x00000a> JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
<FileUpload file_upload id=fil_15A3Gj2eZvKYlo2C0NxXGm4s at 0x00000a> JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
Stripe\FileUpload JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
com.stripe.model.FileUpload JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
{
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}
&stripe.FileUpload JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}

List all file uploads

Returns a list of the files that you have uploaded to Stripe. The file uploads are returned sorted by creation date, with the most recently created file uploads appearing first.

Arguments

  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

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

  • purpose optional

    The file purpose to filter queries by. If none is provided, files will not be filtered by purpose.

  • 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 arrayMapobjectmap with a data property that contains an array of up to limit file uploads, starting after file upload starting_after. Each entry in the array is a separate file upload object. If no more file uploads are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrowreturn an an error.

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

GET https://uploads.stripe.com/v1/files
Stripe::FileUpload.all
stripe.FileUpload.all()
\Stripe\FileUpload::all();
FileUpload.all(Map<String, Object> options);
stripe.fileUploads.list();
fileupload.List()
 
curl https://uploads.stripe.com/v1/files?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::FileUpload.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.FileUpload.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\FileUpload::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> fileUploadParams = new HashMap<String, Object>();
fileUploadParams.put("limit", 3);

Fileupload.all(fileUploadParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.fileUploads.list(
  { limit: 3 },
  function(err, fileUploads) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.FileuploadListParams{}
params.Filters.AddFilter("limit", "", "3")
i := fileupload.List(params)
for i.Next() {
  f := i.Fileupload()
}
 
{
  "object": "list",
  "url": "/v1/files",
  "has_more": false,
  "data": [
    {
      "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
      "object": "file_upload",
      "created": 1418666909,
      "purpose": "dispute_evidence",
      "size": 1529506,
      "type": "pdf"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/files",
  "has_more": false,
  "data": [
    #<Stripe::FileUpload id=fil_15A3Gj2eZvKYlo2C0NxXGm4s 0x00000a> JSON: {
      "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
      "object": "file_upload",
      "created": 1418666909,
      "purpose": "dispute_evidence",
      "size": 1529506,
      "type": "pdf"
    },
    #<Stripe::FileUpload[...] ...>,
    #<Stripe::FileUpload[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/files",
  has_more: false,
  data: [
    <FileUpload file_upload id=fil_15A3Gj2eZvKYlo2C0NxXGm4s at 0x00000a> JSON: {
      "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
      "object": "file_upload",
      "created": 1418666909,
      "purpose": "dispute_evidence",
      "size": 1529506,
      "type": "pdf"
    },
    <stripe.FileUpload[...] ...>,
    <stripe.FileUpload[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/files",
  "has_more" => false,
  "data" => [
    [0] => Stripe\FileUpload JSON: {
      "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
      "object": "file_upload",
      "created": 1418666909,
      "purpose": "dispute_evidence",
      "size": 1529506,
      "type": "pdf"
    }
    [1] => <Stripe\FileUpload[...] ...>
    [2] => <Stripe\FileUpload[...] ...>
  ]
}
#<com.stripe.model.FileUploadCollection id=#> JSON: {
  "data": [
    com.stripe.model.FileUpload JSON: {
      "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
      "object": "file_upload",
      "created": 1418666909,
      "purpose": "dispute_evidence",
      "size": 1529506,
      "type": "pdf"
    },
    #<com.stripe.model.FileUpload[...] ...>,
    #<com.stripe.model.FileUpload[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/files",
  "has_more": false,
  "data": [
    {
      "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
      "object": "file_upload",
      "created": 1418666909,
      "purpose": "dispute_evidence",
      "size": 1529506,
      "type": "pdf"
    },
    {...},
    {...}
  ]
}
&stripe.FileUpload JSON: {
  "id": "fil_15A3Gj2eZvKYlo2C0NxXGm4s",
  "object": "file_upload",
  "created": 1418666909,
  "purpose": "dispute_evidence",
  "size": 1529506,
  "type": "pdf"
}

Refunds

Refund objects allow you to refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged. The fees you were originally charged are also refunded.

The refund object

Attributes

  • id string

  • object string , value is "refund"

  • amount integer

    Amount, in cents.

  • balance_transaction string

    Balance transaction that describes the impact on your account balance.

  • charge string

    ID of the charge that was refunded.

  • created timestamp

  • currency currency

    Three-letter ISO code representing the currency.

  • description string

  • metadata #

    A set of key/value pairs that you can attach to the object. It can be useful for storing additional information in a structured format.

  • reason string

    Reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer.

  • receipt_number string

    This is the transaction number that appears on email receipts sent for this refund. 

{
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
#<Stripe::Refund id=re_17YeHA2eZvKYlo2Cj7u4p5rS 0x00000a> JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
<Refund refund id=re_17YeHA2eZvKYlo2Cj7u4p5rS at 0x00000a> JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
Stripe\Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
com.stripe.model.Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
{
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
&stripe.Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}

Create a refund

When you create a new refund, you must specify a charge to create it on.

Creating a new refund will refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged. The fees you were originally charged are also refunded.

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 returnraiseraisethrowthrowthrowreturn an an error when called on an already-refunded charge, or when trying to refund more money than is left on a charge.

Arguments

  • charge required

    The identifier of the charge to refund.

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

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund 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 nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

  • reason optional, default is null

    String indicating the reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer. Specifying fraudulent as the reason when you believe the charge to be fraudulent will help us improve our fraud detection algorithms.

  • refund_application_fee connect only optional, default is false

    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.

  • reverse_transfer connect only optional, default is false

    Boolean indicating whether the transfer should be reversed when refunding this charge. The transfer will be reversed for the same amount being refunded (either the entire or partial amount).

    A transfer can only be reversed by the application that created the charge.

Returns

Returns the refund object if the refund succeeded. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an 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}/refunds
Stripe::Refund.create
stripe.Refund.create()
\Stripe\Charge::create();
Map params = new HashMap();
Refund.create(params);
stripe.refunds.create(
  {},
  function(err, refund) {
  }
);
refund.New(&stripe.RefundParams{Charge: {CHARGE_ID}})
 
curl https://api.stripe.com/v1/refunds \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d charge=ch_17YeVf2eZvKYlo2CbSkw0Av7

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

re = Stripe::Refund.create(
  charge: "ch_17YeVf2eZvKYlo2CbSkw0Av7"
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

re = stripe.Refund.create(
  charge="ch_17YeVf2eZvKYlo2CbSkw0Av7"
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$re = \Stripe\Refund::create(array(
  "charge" => "ch_17YeVf2eZvKYlo2CbSkw0Av7"
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> refundParams = new HashMap<String, Object>();
refundParams.put("charge", "ch_17YeVf2eZvKYlo2CbSkw0Av7");

Refund.create(refundParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.refunds.create({
  charge: "ch_17YeVf2eZvKYlo2CbSkw0Av7"
}, function(err, refund) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := refund.New(&stripe.RefundParams{Charge: "ch_17YeVf2eZvKYlo2CbSkw0Av7"})
 
{
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
#<Stripe::Refund id=re_17YeHA2eZvKYlo2Cj7u4p5rS 0x00000a> JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
<Refund refund id=re_17YeHA2eZvKYlo2Cj7u4p5rS at 0x00000a> JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
Stripe\Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
com.stripe.model.Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
{
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
&stripe.Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}

Retrieve a refund

Retrieves the details of an existing refund.

Arguments

  • refund required

    ID of refund to retrieve.

Returns

Returns a refund if a valid ID was provided. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error otherwise. 

curl https://api.stripe.com/v1/refunds/re_17YeHA2eZvKYlo2Cj7u4p5rS \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Refund.retrieve("re_17YeHA2eZvKYlo2Cj7u4p5rS")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Refund.retrieve("re_17YeHA2eZvKYlo2Cj7u4p5rS")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Refund::retrieve("re_17YeHA2eZvKYlo2Cj7u4p5rS");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Refund.retrieve("re_17YeHA2eZvKYlo2Cj7u4p5rS");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.refunds.retrieve(
  "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  function(err, refund) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := refund.Get("re_17YeHA2eZvKYlo2Cj7u4p5rS", nil)
 
{
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
#<Stripe::Refund id=re_17YeHA2eZvKYlo2Cj7u4p5rS 0x00000a> JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
<Refund refund id=re_17YeHA2eZvKYlo2Cj7u4p5rS at 0x00000a> JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
Stripe\Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
com.stripe.model.Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
{
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}
&stripe.Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}

Update a refund

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

This request only accepts metadata as an argument.

Arguments

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund 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 nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

Returns

Returns the refund object if the update succeeded. This call will returnraiseraisethrowthrowthrowreturn an an error if update parameters are invalid. 

POST https://api.stripe.com/v1/refunds/{REFUND_ID}
refund = Stripe::Refund.retrieve({REFUND_ID})
refund.metadata[{KEY}] = {VALUE}
refund.save
refund = stripe.Refund.retrieve({REFUND_ID})
refund.metadata[{KEY}] = {VALUE}
refund.save()
$refund = \Stripe\Refund::retrieve({REFUND_ID});
$refund->metadata[{KEY}] = {VALUE};
$refund->save();
Refund refund = Refund.retrieve({REFUND_ID});
Map metadata = new HashMap();
metdata.put({KEY}, {VALUE});
Map params = new HashMap();
params.put("metadata", metadata);
refund.update(params);
stripe.refunds.update({REFUND_ID}, {
  metadata: {{KEY}: {VALUE}}
})
refund.Update({REFUND_ID}, &stripe.RefundParams{
  Meta: map[string]string{{KEY}: {VALUE}}
})
 
curl https://api.stripe.com/v1/refunds/re_17YeHA2eZvKYlo2Cj7u4p5rS \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

re = Stripe::Refund.retrieve("re_17YeHA2eZvKYlo2Cj7u4p5rS")
re.metadata["key"] = "value"
re.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

re = stripe.Refund.retrieve("re_17YeHA2eZvKYlo2Cj7u4p5rS")
re.metadata["key"] = "value"
re.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$re = \Stripe\Refund::retrieve("re_17YeHA2eZvKYlo2Cj7u4p5rS");
$re->metadata["key"] = "value";
$re->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Refund re = Refund.retrieve("re_17YeHA2eZvKYlo2Cj7u4p5rS");
Map<String, String> metadata = new HashMap<String, String>();
metadata.put("key", "value");
Map<String, Object> params = new HashMap<String, Object>();
params.put("metadata", metadata);
re.update(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.refund.update(
  "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  { metadata: { key: "value"} },
  function(err, refund) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ref, err := refund.Update(
  "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  &stripe.RefundParams{
    Meta: map[string]string{ "key": "value" },
  })
 
{
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
#<Stripe::Refund id=re_17YeHA2eZvKYlo2Cj7u4p5rS 0x00000a> JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
<Refund refund id=re_17YeHA2eZvKYlo2Cj7u4p5rS at 0x00000a> JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
Stripe\Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
com.stripe.model.Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
{
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}
&stripe.Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "reason": null,
  "receipt_number": null
}

List all refunds

Returns a list of all refunds you’ve previously created. The refunds are returned in sorted order, with the most recent refunds appearing first. For convenience, the 10 most recent refunds are always available by default on the charge object.

Arguments

  • charge optional

    Only return refunds for the charge specified by this charge 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 arrayMapobjectmap with a data property that contains an array of up to limit refunds, starting after refund starting_after. Each entry in the array is a separate refund object. If no more refunds are available, the resulting array will be empty. If you provide a non-existent charge ID, this call returnsraisesraisesthrowsthrowsthrowsreturns an error.

You can optionally request that the response includes the total count of all refunds that match your filters by specifying include[]=total_count in your request.

GET https://api.stripe.com/v1/refunds
Stripe::Refund.all
stripe.Refund.all()
\Stripe\Refund::all();
Refund.all(Map<String, Object> options);
stripe.refunds.list();
refund.List()
 
curl https://api.stripe.com/v1/refunds?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Refund.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Refund.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Refund::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> refundParams = new HashMap<String, Object>();
refundParams.put("limit", 3);

Refund.all(refundParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.refunds.list(
  { limit: 3 },
  function(err, refunds) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.RefundListParams{}
params.Filters.AddFilter("limit", "", "3")
i := refund.List(params)
for i.Next() {
  r := i.Refund()
}
 
{
  "object": "list",
  "url": "/v1/refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
      "object": "refund",
      "amount": 100,
      "balance_transaction": null,
      "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
      "created": 1454081708,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/refunds",
  "has_more": false,
  "data": [
    #<Stripe::Refund id=re_17YeHA2eZvKYlo2Cj7u4p5rS 0x00000a> JSON: {
      "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
      "object": "refund",
      "amount": 100,
      "balance_transaction": null,
      "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
      "created": 1454081708,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    },
    #<Stripe::Refund[...] ...>,
    #<Stripe::Refund[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/refunds",
  has_more: false,
  data: [
    <Refund refund id=re_17YeHA2eZvKYlo2Cj7u4p5rS at 0x00000a> JSON: {
      "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
      "object": "refund",
      "amount": 100,
      "balance_transaction": null,
      "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
      "created": 1454081708,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    },
    <stripe.Refund[...] ...>,
    <stripe.Refund[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/refunds",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Refund JSON: {
      "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
      "object": "refund",
      "amount": 100,
      "balance_transaction": null,
      "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
      "created": 1454081708,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    }
    [1] => <Stripe\Refund[...] ...>
    [2] => <Stripe\Refund[...] ...>
  ]
}
#<com.stripe.model.RefundCollection id=#> JSON: {
  "data": [
    com.stripe.model.Refund JSON: {
      "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
      "object": "refund",
      "amount": 100,
      "balance_transaction": null,
      "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
      "created": 1454081708,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    },
    #<com.stripe.model.Refund[...] ...>,
    #<com.stripe.model.Refund[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
      "object": "refund",
      "amount": 100,
      "balance_transaction": null,
      "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
      "created": 1454081708,
      "currency": "usd",
      "metadata": {
      },
      "reason": null,
      "receipt_number": null
    },
    {...},
    {...}
  ]
}
&stripe.Refund JSON: {
  "id": "re_17YeHA2eZvKYlo2Cj7u4p5rS",
  "object": "refund",
  "amount": 100,
  "balance_transaction": null,
  "charge": "ch_17W6wF2eZvKYlo2CpMeYAHPx",
  "created": 1454081708,
  "currency": "usd",
  "metadata": {
  },
  "reason": null,
  "receipt_number": null
}

Tokens

Often you want to be able to charge credit cards or send payments to bank accounts without having to hold sensitive card information on your own servers. Stripe.js makes this easy in the browser, but you can use the same technique in other environments with our token API.

Tokens can be created with your publishable API key, which can safely be embedded in downloadable applications like iPhone and Android apps. You can then use a token anywhere in our API that a card or bank account is accepted. Note that tokens are not meant to be stored or used more than once—to store these details for use later, you should create Customer or Recipient objects.

The token object

Attributes

  • id string

  • object string , value is "token"

  • bank_account hash

    Hash describing the bank account

    child attributes

    • id string

    • object string , value is "bank_account"

    • account_holder_type string

      The type of entity that holds the account. This can be either individual or company.

    • bank_name string

      Name of the bank associated with the routing number, e.g. WELLS FARGO.

    • country string

      Two-letter ISO code representing the country the bank account is located in.

    • currency currency

      Three-letter ISO currency code representing the currency paid out to the bank account.

    • fingerprint string

      Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.

    • last4 string

    • name string

      The name of the person or business that owns the bank account.

    • routing_number string

      The routing transit number for the bank account.

    • status string

      Possible values are new, validated, verified, verification_failed, or errored. A bank account that hasn’t had any activity or validation performed is new. If Stripe can determine that the bank account exists, its status will be validated. Note that there often isn’t enough information to know (e.g. for smaller credit unions), and the validation is not always run. If customer bank account verification has succeeded, the bank account status will be verified. If the verification failed for any reason, such as microdeposit failure, the status will be verification_failed. If a transfer sent to this bank account fails, we’ll set the status to errored and will not continue to send transfers until the bank details are updated.

  • card hash

    Hash describing the card used to make the charge

    child attributes

    • id string

      ID of card (used in conjunction with a customer or recipient ID)

    • object string , value is "card"

    • 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, unavailable, 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, unavailable, or unchecked.

    • brand string

      Card brand. Can be Visa, American Express, MasterCard, Discover, JCB, Diners Club, or Unknown.

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

    • currency currency

    • cvc_check string

      If a CVC was provided, results of the check: pass, fail, unavailable, or unchecked

    • dynamic_last4 string

      (For tokenized numbers only.) The last four digits of the device account number.

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

    • funding string

      Card funding type. Can be credit, debit, prepaid, or unknown

    • last4 string

    • metadata #

      A set of key/value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format.

    • name string

      Cardholder name

    • tokenization_method string

      If the card number is tokenized, this is the method that was used. Can be apple_pay or android_pay.

  • client_ip string

    IP address of the client that generated the token

  • created timestamp

  • livemode boolean

  • type string

    Type of the token: card or bank_account

  • used boolean

    Whether or not this token has already been used (tokens can be used only once) 

{
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
#<Stripe::Token id=tok_17YYPH2eZvKYlo2C8ZbpILPR 0x00000a> JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
<Token token id=tok_17YYPH2eZvKYlo2C8ZbpILPR at 0x00000a> JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
Stripe\Token JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
com.stripe.model.Token JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
{
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
&stripe.Token JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}

Create a card token

Creates a single use token that wraps the details of a credit card. This token can be used in place of a credit card dictionaryhashdictionaryassociative arrayMapobjectmap with any API method. These tokens can only be used once: by creating a new charge object, or attaching them to a customer.

Arguments

  • card optional

    The card this token will represent. If you also pass in a customer, the card must be the ID of a card belonging to the customer. Otherwise, if you do not pass a customer, a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's credit card details, with the options described below.

    child parameters

    • exp_monthexp_monthexp_monthexp_monthexp_monthexp_monthexp_month required

      Two digit number representing the card's expiration month.

    • exp_yearexp_yearexp_yearexp_yearexp_yearexp_yearexp_year required

      Two or four digit number representing the card's expiration year.

    • numbernumbernumbernumbernumbernumbernumber required

      The card number, as a string without any separators.

    • address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city optional

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

    • currencycurrencycurrencycurrencycurrencycurrencycurrency managed accounts only

      Required to be able to add the card to an account (in all other cases, this parameter is not used). When added to an account, the card (which must be a debit card) can be used as a transfer destination for funds in this currency. Currently, the only supported currency for debit card transfers is usd.

    • cvccvccvccvccvccvccvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • namenamenamenamenamenamename optional

      Cardholder's full name.

  • customer optional

    For use with Stripe Connect only; this can only be used with an OAuth access token or Stripe-Account header.. For more details, see the shared customers documentation. A customer (owned by the application's account) to create a token for.

Returns

The created card token object is returned if successful. Otherwise, this call returnsraisesraisesthrowsthrowsthrowsreturns an error. 

POST https://api.stripe.com/v1/tokens
Stripe::Token.create()
stripe.Token.create()
\Stripe\Token::create();
Token.create();
stripe.tokens.create();
token.New()
curl https://api.stripe.com/v1/tokens \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d card[number]=4242424242424242 \
   -d card[exp_month]=12 \
   -d card[exp_year]=2017 \
   -d card[cvc]=123

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Token.create(
  :card => {
    :number => "4242424242424242",
    :exp_month => 1,
    :exp_year => 2017,
    :cvc => "314"
  },
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Token.create(
  card={
    "number": '4242424242424242',
    "exp_month": 12,
    "exp_year": 2017,
    "cvc": '123'
  },
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Token::create(array(
  "card" => array(
    "number" => "4242424242424242",
    "exp_month" => 1,
    "exp_year" => 2017,
    "cvc" => "314"
  )
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> tokenParams = new HashMap<String, Object>();
Map<String, Object> cardParams = new HashMap<String, Object>();
cardParams.put("number", "4242424242424242");
cardParams.put("exp_month", 1);
cardParams.put("exp_year", 2017);
cardParams.put("cvc", "314");
tokenParams.put("card", cardParams);

Token.create(tokenParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.tokens.create({
  card: {
    "number": '4242424242424242',
    "exp_month": 12,
    "exp_year": 2017,
    "cvc": '123'
  }
}, function(err, token) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

t, err := token.New(&stripe.TokenParams{
  Card: &stripe.CardParams{
        Number: "4242424242424242",
        Month:  "12",
        Year:   "2017",
        CVC:    "123",
    },
})
{
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
#<Stripe::Token id=tok_17YYPH2eZvKYlo2C8ZbpILPR 0x00000a> JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
<Token token id=tok_17YYPH2eZvKYlo2C8ZbpILPR at 0x00000a> JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
Stripe\Token JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
com.stripe.model.Token JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
{
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
&stripe.Token JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}

Create a bank account token

Creates a single use token that wraps the details of a bank account. This token can be used in place of a bank account dictionaryhashdictionaryassociative arrayMapobjectmap with any API method. These tokens can only be used once: by attaching them to a recipient or managed account.

Arguments

  • bank_account optional, default is nullnilNonenullnullnullnull

    The bank account this token will represent.

    child arguments

    • account_numberaccount_numberaccount_numberaccount_numberaccount_numberaccount_numberaccount_number required

      The account number for the bank account in string form. Must be a checking account.

    • countrycountrycountrycountrycountrycountrycountry required

      The country the bank account is in.

    • currencycurrencycurrencycurrencycurrencycurrencycurrency required

      The currency the bank account is in. This must be a country/currency pairing that Stripe supports.

    • routing_numberrouting_numberrouting_numberrouting_numberrouting_numberrouting_numberrouting_number optional

      The routing number, sort code, or other country-appropriate institution number for the bank account. For US bank accounts, this is required and should be the ACH routing number, not the wire routing number. If you are providing an IBAN for account_number, this field is not required.

    • namenamenamenamenamenamename optional

      The name of the person or business that owns the bank account. This field is required when attaching the bank account to a customer object.

    • account_holder_typeaccount_holder_typeaccount_holder_typeaccount_holder_typeaccount_holder_typeaccount_holder_typeaccount_holder_type optional

      The type of entity that holds the account. This can be either "individual" or "company". This field is required when attaching the bank account to a customer object.

Returns

The created bank account token object is returned if successful. Otherwise, this call returnsraisesraisesthrowsthrowsthrowsreturns an error. 

POST https://api.stripe.com/v1/tokens
Stripe::Token.create()
stripe.Token.create()
\Stripe\Token::create();
Token.create();
stripe.tokens.create();
token.New()
curl https://api.stripe.com/v1/tokens \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d bank_account[country]=US \
   -d bank_account[currency]=usd \
   -d bank_account[name]="Jane Austen" \
   -d bank_account[account_holder_type]=individual \
   -d bank_account[routing_number]=110000000 \
   -d bank_account[account_number]=000123456789

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Token.create(
    :bank_account => {
    :country => "US",
    :currency => "usd",
    :name => "Jane Austen",
    :account_holder_type => "individual",
    :routing_number => "1100000000",
    :account_number => "000123456789",
  },
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Token.create(
  bank_account={
    "country": 'US',
    "currency": 'usd',
    "name": 'Jane Austen',
    "account_holder_type": 'individual',
    "routing_number": '110000000',
    "account_number": '000123456789'
  },
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Token::create(array(
    "bank_account" => array(
    "country" => "US",
    "currency" => "usd",
    "name" => "Jane Austen",
    "account_holder_type" => "individual",
    "routing_number" => "110000000",
    "account_number" => "000123456789"
  )
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> tokenParams = new HashMap<String, Object>();
Map<String, Object> bank_accountParams = new HashMap<String, Object>();
bank_accountParams.put("country", "US");
bank_accountParams.put("currency", "usd");
bank_accountParams.put("name", "Jane Austen");
bank_accountParams.put("account_holder_type", "individual");
bank_accountParams.put("routing_number", "110000000");
bank_accountParams.put("account_number", "000123456789");
tokenParams.put("bank_account", bank_accountParams);

Token.create(tokenParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.tokens.create({
  bank_account: {
    country: 'US',
    currency: 'usd',
    name: 'Jane Austen',
    account_holder_type: 'individual',
    routing_number: '110000000',
    account_number: '000123456789'
  }
}, function(err, token) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

t, err := token.New(&stripe.TokenParams{
  Bank: &stripe.BankAccountParams{
      Country: "US",
      Currency: "usd",
      Name: "Jane Austen",
      AccountHolderType: "individual",
      Routing: "110000000",
      Account: "000123456789",
    },
})
{
  "id": "btok_7oH6klHpw9qiLV",
  "object": "token",
  "bank_account": {
    "id": "ba_17YeYO2eZvKYlo2Cr6p4nsT4",
    "object": "bank_account",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1454082776,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
#<Stripe::Token id=btok_7oH6klHpw9qiLV 0x00000a> JSON: {
  "id": "btok_7oH6klHpw9qiLV",
  "object": "token",
  "bank_account": {
    "id": "ba_17YeYO2eZvKYlo2Cr6p4nsT4",
    "object": "bank_account",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1454082776,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
<Token token id=btok_7oH6klHpw9qiLV at 0x00000a> JSON: {
  "id": "btok_7oH6klHpw9qiLV",
  "object": "token",
  "bank_account": {
    "id": "ba_17YeYO2eZvKYlo2Cr6p4nsT4",
    "object": "bank_account",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1454082776,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
Stripe\Token JSON: {
  "id": "btok_7oH6klHpw9qiLV",
  "object": "token",
  "bank_account": {
    "id": "ba_17YeYO2eZvKYlo2Cr6p4nsT4",
    "object": "bank_account",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1454082776,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
com.stripe.model.Token JSON: {
  "id": "btok_7oH6klHpw9qiLV",
  "object": "token",
  "bank_account": {
    "id": "ba_17YeYO2eZvKYlo2Cr6p4nsT4",
    "object": "bank_account",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1454082776,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
{
  "id": "btok_7oH6klHpw9qiLV",
  "object": "token",
  "bank_account": {
    "id": "ba_17YeYO2eZvKYlo2Cr6p4nsT4",
    "object": "bank_account",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1454082776,
  "livemode": false,
  "type": "bank_account",
  "used": false
}
&stripe.Token JSON: {
  "id": "btok_7oH6klHpw9qiLV",
  "object": "token",
  "bank_account": {
    "id": "ba_17YeYO2eZvKYlo2Cr6p4nsT4",
    "object": "bank_account",
    "account_holder_type": "individual",
    "bank_name": "STRIPE TEST BANK",
    "country": "US",
    "currency": "usd",
    "fingerprint": "1JWtPxqbdX5Gamtc",
    "last4": "6789",
    "name": "Jane Austen",
    "routing_number": "110000000",
    "status": "new"
  },
  "client_ip": null,
  "created": 1454082776,
  "livemode": false,
  "type": "bank_account",
  "used": false
}

Retrieve a token

Retrieves the token with the given ID.

Arguments

  • token required

    The ID of the desired token.

Returns

Returns a token if a valid ID was provided. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error otherwise. 

GET https://api.stripe.com/v1/tokens/{TOKEN_ID}
Stripe::Token.retrieve({TOKEN_ID})
stripe.Token.retrieve({TOKEN_ID})
\Stripe\Token::retrieve({TOKEN_ID});
Token.retrieve({TOKEN_ID});
stripe.tokens.retrieve({TOKEN_ID}, function(err, obj) {...});
token.Get({TOKEN_ID})
curl https://api.stripe.com/v1/tokens/tok_17YYPH2eZvKYlo2C8ZbpILPR \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Token.retrieve("tok_17YYPH2eZvKYlo2C8ZbpILPR")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Token.retrieve("tok_17YYPH2eZvKYlo2C8ZbpILPR")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Token::retrieve("tok_17YYPH2eZvKYlo2C8ZbpILPR");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Token.retrieve("tok_17YYPH2eZvKYlo2C8ZbpILPR");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.tokens.retrieve(
  "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  function(err, token) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

t, err := token.Get("tok_17YYPH2eZvKYlo2C8ZbpILPR", nil)
{
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
#<Stripe::Token id=tok_17YYPH2eZvKYlo2C8ZbpILPR 0x00000a> JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
<Token token id=tok_17YYPH2eZvKYlo2C8ZbpILPR at 0x00000a> JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
Stripe\Token JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
com.stripe.model.Token JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
{
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}
&stripe.Token JSON: {
  "id": "tok_17YYPH2eZvKYlo2C8ZbpILPR",
  "object": "token",
  "card": {
    "id": "card_17YYPH2eZvKYlo2CNLnUT0Gd",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": null,
    "brand": "Visa",
    "country": "US",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 8,
    "exp_year": 2017,
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "client_ip": null,
  "created": 1454059147,
  "livemode": false,
  "type": "card",
  "used": false
}

Transfers

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

View the documentation on creating transfers via the API.

The transfer object

Attributes

  • id string

  • object string , value is "transfer"

  • amount integer

    Amount (in cents) to be transferred to your bank account

  • amount_reversed integer

    Amount in cents reversed (can be less than the amount attribute on the transfer if a partial reversal was issued).

  • application_fee string

  • balance_transaction string

    Balance transaction that describes the impact of this transfer on your account balance.

  • created timestamp

    Time that this record of the transfer was first created.

  • currency currency

  • date timestamp

    Date the transfer is scheduled to arrive in the bank. This doesn’t factor in delays like weekends or bank holidays.

  • description string

    Internal-only description of the transfer

  • destination string

    ID of the bank account, card, or Stripe account the transfer was sent to.

  • destination_payment string

    If the destination is a Stripe account, this will be the ID of the payment that the destination account received for the transfer.

  • failure_code string

    Error code explaining reason for transfer failure if available. See Types of transfer failures for a list of failure codes.

  • failure_message string

    Message to user further explaining reason for transfer failure if available.

  • livemode boolean

  • metadata #

    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.

  • reversals list

    A list of reversals that have been applied to the transfer.

    child attributes

    • object string , value is "list"

    • data list

      child attributes

      • id string

      • object string , value is "list"

      • amount integer

        Amount, in cents.

      • balance_transaction string

        Balance transaction that describes the impact on your account balance.

      • created timestamp

      • currency currency

        Three-letter ISO code representing the currency.

      • metadata #

        A set of key/value pairs that you can attach to the object. It can be useful for storing additional information in a structured format.

      • transfer string

        ID of the transfer that was reversed.

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • reversed boolean

    Whether or not the transfer has been fully reversed. If the transfer is only partially reversed, this attribute will still be false.

  • source_transaction string

    ID of the charge (or other transaction) that was used to fund the transfer. If null, the transfer was funded from the available balance.

  • source_type string

    The source balance this transfer came from. One of card, bank_account, bitcoin_receiver, or alipay_account

  • statement_descriptor string

    Extra information about a transfer to be displayed on the user’s bank statement.

  • status string

    Current status of the transfer (paid, pending, in_transit, canceled or failed). A transfer will be pending until it is submitted to the bank, at which point it becomes in_transit. It will then change to paid if the transaction goes through. If it does not go through successfully, its status will change to failed or canceled.

  • type string

    Can be card, bank_account, or stripe_account. 

{
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
#<Stripe::Transfer id=tr_17YUE12eZvKYlo2C9i06Mk0C 0x00000a> JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
<Transfer transfer id=tr_17YUE12eZvKYlo2C9i06Mk0C at 0x00000a> JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
Stripe\Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
com.stripe.model.Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
{
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
&stripe.Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}

Create a transfer

To send funds from your Stripe account to a third-party recipient or to your own 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.

If you are creating a manual transfer or a special case transfer on a Stripe account that uses multiple payment source types, you'll need to specify the source type balance that the transfer should draw from. The balance object details available and pending amounts by source type.

Arguments

  • amount required

    A positive integer in cents representing how much to transfer.

  • currency required

    3-letter ISO code for currency.

  • destination required

    The id of a bank account or a card to send the transfer to, or the string default_for_currency to use the default external account for the specified currency.

    If you use Stripe Connect, this can be the the id of a connected Stripe account; see the details about when such transfers are permitted.

  • description optional, default is nullnilNonenullnullnullnull

    An arbitrary string which you can attach to a transfer object. It is displayed when in the web interface alongside the transfer.

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

  • source_transaction optional, default is nullnilNonenullnullnullnull

    You can use this parameter to transfer funds from a charge (or other transaction) before they are added to your available balance. A pending balance will transfer immediately but the funds will not become available until the original charge becomes available. See the Connect documentation for details.

  • statement_descriptor optional, default is nullnilNonenullnullnullnull

    A string to be displayed on the recipient's bank or card statement. This may be at most 22 characters. Attempting to use a statement_descriptor longer than 22 characters will return an error. Note: Most banks will truncate this information and/or display it inconsistently. Some may not display it at all.

  • source_type optional, default is card

    The source balance to draw this transfer from. Balances for different payment sources are kept separately. You can find the amounts with the balances API. Valid options are card, alipay_account, bitcoin_receiver.

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/transfers
Stripe::Transfer.create
stripe.Transfer.create()
\Stripe\Transfer::create();
Transfer.create();
stripe.transfers.create();
transfer.New()
 
curl https://api.stripe.com/v1/transfers \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=400 \
   -d currency=usd \
   -d destination=acct_1032D82eZvKYlo2C \
   -d description="Transfer to test@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Transfer.create(
  :amount => 400,
  :currency => "usd",
  :destination => "acct_1032D82eZvKYlo2C",
  :description => "Transfer for test@example.com"
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Transfer.create(
  amount=400,
  currency="usd",
  destination="acct_1032D82eZvKYlo2C",
  description="Transfer for test@example.com"
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Transfer::create(array(
  "amount" => 400,
  "currency" => "usd",
  "destination" => "acct_1032D82eZvKYlo2C",
  "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("destination", "acct_1032D82eZvKYlo2C");
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",
  destination: "acct_1032D82eZvKYlo2C"
  description: "Transfer for test@example.com"
}, function(err, transfer) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

t, err := transfer.New(&stripe.TransferParams{
  Amount: 400,
  Currency: "usd",
  Dest: "acct_1032D82eZvKYlo2C"
  Desc: "Transfer for test@example.com",
})
 
{
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
#<Stripe::Transfer id=tr_17YUE12eZvKYlo2C9i06Mk0C 0x00000a> JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
<Transfer transfer id=tr_17YUE12eZvKYlo2C9i06Mk0C at 0x00000a> JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
Stripe\Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
com.stripe.model.Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
{
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
&stripe.Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}

Retrieve 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 returnsraisesraisesthrowsthrowsthrowsreturns an error otherwise.

curl https://api.stripe.com/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Transfer::retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.transfers.retrieve(
  "tr_17YUE12eZvKYlo2C9i06Mk0C",
  function(err, transfer) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

t, err := transfer.Get("tr_17YUE12eZvKYlo2C9i06Mk0C", nil)
 
{
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
#<Stripe::Transfer id=tr_17YUE12eZvKYlo2C9i06Mk0C 0x00000a> JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
<Transfer transfer id=tr_17YUE12eZvKYlo2C9i06Mk0C at 0x00000a> JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
Stripe\Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
com.stripe.model.Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
{
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
&stripe.Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}

Update 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 nullnilNonenullnullnullnull

    An arbitrary string which you can attach to a transfer object. It is displayed when in the web interface alongside the transfer. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull 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 nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

Returns

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

POST https://api.stripe.com/v1/transfers/{TRANSFER_ID}
tr = Stripe::Transfer.retrieve({TRANSFER_ID})
tr.description = {NEW_DESCRIPTION}
...
tr.save
tr = stripe.Transfer.retrieve({TRANSFER_ID})
tr.description = {NEW_DESCRIPTION}
...
tr.save()
$tr = \Stripe\Transfer::retrieve({TRANSFER_ID});
$tr->description = {NEW_DESCRIPTION};
...
$tr->save();
Transfer tr = Transfer.retrieve({TRANSFER_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", {NEW_DESCRIPTION});
...
tr.update(updateParams);
stripe.transfers.update({TRANSFER_ID}, {
  description: {NEW_DESCRIPTION}
});
transfer.Update({TRANSFER_ID}, &stripe.TransferParams{Desc: {NEW_DESCRIPTION}})
 
curl https://api.stripe.com/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Transfer for test@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

tr = Stripe::Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C")
tr.description = "Transfer for test@example.com"
tr.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

tr = stripe.Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C")
tr.description = "Transfer for test@example.com"
tr.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$tr = \Stripe\Transfer::retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C");
$tr->description = "Transfer for test@example.com";
$tr->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Transfer tr = Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C");
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_17YeVf2eZvKYlo2CbSkw0Av7",
  {
      description: "Transfer for test@example.com"
  },
  function(err, transfer) {
      // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

t, err := transfer.Update(
  "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  &stripe.TransferParams{Desc: "Transfer for test@example.com"},
)
 
{
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": "Transfer to test@example.com",
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
#<Stripe::Transfer id=tr_17YUE12eZvKYlo2C9i06Mk0C 0x00000a> JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": "Transfer to test@example.com",
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
<Transfer transfer id=tr_17YUE12eZvKYlo2C9i06Mk0C at 0x00000a> JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": "Transfer to test@example.com",
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
Stripe\Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": "Transfer to test@example.com",
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
com.stripe.model.Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": "Transfer to test@example.com",
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
{
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": "Transfer to test@example.com",
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}
&stripe.Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": "Transfer to test@example.com",
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}

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 dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • date optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object date field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the date field is after this timestamp.

    • gte optional

      Return values where the date field is after or equal to this timestamp.

    • lt optional

      Return values where the date field is before this timestamp.

    • lte optional

      Return values where the date field is before or equal to this timestamp.

  • 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, failed, in_transit, or canceled.

Returns

A dictionaryhashdictionaryassociative arrayMapobjectmap 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 transfers are available, the resulting array will be empty. If you provide a non-existent recipient ID, this call returnsraisesraisesthrowsthrowsthrowsreturns 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/transfers
Stripe::Transfer.all
stripe.Transfer.all()
\Stripe\Transfer::all();
Transfer.all(Map<String, Object> options);
stripe.transfers.list();
transfer.List()
 
curl https://api.stripe.com/v1/transfers?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Transfer.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Transfer.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Transfer::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> transferParams = new HashMap<String, Object>();
transferParams.put("limit", 3);

Transfer.all(transferParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.transfers.list(
  { limit: 3 },
  function(err, transfers) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.TransferListParams{}
params.Filters.AddFilter("limit", "", "3")
i := transfer.List(params)
for i.Next() {
  t := i.Transfer()
}
 
{
  "object": "list",
  "url": "/v1/transfers",
  "has_more": false,
  "data": [
    {
      "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
      "object": "transfer",
      "amount": 500,
      "amount_reversed": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454043073,
      "currency": "usd",
      "date": 1454043073,
      "description": null,
      "destination": "acct_17YUCRIJjRJCgHYF",
      "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
      "failure_code": null,
      "failure_message": null,
      "livemode": false,
      "metadata": {
      },
      "recipient": null,
      "reversals": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
      },
      "reversed": false,
      "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
      "source_type": "card",
      "statement_descriptor": null,
      "status": "paid",
      "type": "stripe_account"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/transfers",
  "has_more": false,
  "data": [
    #<Stripe::Transfer id=tr_17YUE12eZvKYlo2C9i06Mk0C 0x00000a> JSON: {
      "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
      "object": "transfer",
      "amount": 500,
      "amount_reversed": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454043073,
      "currency": "usd",
      "date": 1454043073,
      "description": null,
      "destination": "acct_17YUCRIJjRJCgHYF",
      "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
      "failure_code": null,
      "failure_message": null,
      "livemode": false,
      "metadata": {
      },
      "recipient": null,
      "reversals": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
      },
      "reversed": false,
      "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
      "source_type": "card",
      "statement_descriptor": null,
      "status": "paid",
      "type": "stripe_account"
    },
    #<Stripe::Transfer[...] ...>,
    #<Stripe::Transfer[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/transfers",
  has_more: false,
  data: [
    <Transfer transfer id=tr_17YUE12eZvKYlo2C9i06Mk0C at 0x00000a> JSON: {
      "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
      "object": "transfer",
      "amount": 500,
      "amount_reversed": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454043073,
      "currency": "usd",
      "date": 1454043073,
      "description": null,
      "destination": "acct_17YUCRIJjRJCgHYF",
      "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
      "failure_code": null,
      "failure_message": null,
      "livemode": false,
      "metadata": {
      },
      "recipient": null,
      "reversals": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
      },
      "reversed": false,
      "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
      "source_type": "card",
      "statement_descriptor": null,
      "status": "paid",
      "type": "stripe_account"
    },
    <stripe.Transfer[...] ...>,
    <stripe.Transfer[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/transfers",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Transfer JSON: {
      "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
      "object": "transfer",
      "amount": 500,
      "amount_reversed": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454043073,
      "currency": "usd",
      "date": 1454043073,
      "description": null,
      "destination": "acct_17YUCRIJjRJCgHYF",
      "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
      "failure_code": null,
      "failure_message": null,
      "livemode": false,
      "metadata": {
      },
      "recipient": null,
      "reversals": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
      },
      "reversed": false,
      "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
      "source_type": "card",
      "statement_descriptor": null,
      "status": "paid",
      "type": "stripe_account"
    }
    [1] => <Stripe\Transfer[...] ...>
    [2] => <Stripe\Transfer[...] ...>
  ]
}
#<com.stripe.model.TransferCollection id=#> JSON: {
  "data": [
    com.stripe.model.Transfer JSON: {
      "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
      "object": "transfer",
      "amount": 500,
      "amount_reversed": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454043073,
      "currency": "usd",
      "date": 1454043073,
      "description": null,
      "destination": "acct_17YUCRIJjRJCgHYF",
      "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
      "failure_code": null,
      "failure_message": null,
      "livemode": false,
      "metadata": {
      },
      "recipient": null,
      "reversals": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
      },
      "reversed": false,
      "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
      "source_type": "card",
      "statement_descriptor": null,
      "status": "paid",
      "type": "stripe_account"
    },
    #<com.stripe.model.Transfer[...] ...>,
    #<com.stripe.model.Transfer[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/transfers",
  "has_more": false,
  "data": [
    {
      "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
      "object": "transfer",
      "amount": 500,
      "amount_reversed": 0,
      "application_fee": null,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454043073,
      "currency": "usd",
      "date": 1454043073,
      "description": null,
      "destination": "acct_17YUCRIJjRJCgHYF",
      "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
      "failure_code": null,
      "failure_message": null,
      "livemode": false,
      "metadata": {
      },
      "recipient": null,
      "reversals": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
      },
      "reversed": false,
      "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
      "source_type": "card",
      "statement_descriptor": null,
      "status": "paid",
      "type": "stripe_account"
    },
    {...},
    {...}
  ]
}
&stripe.Transfer JSON: {
  "id": "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "object": "transfer",
  "amount": 500,
  "amount_reversed": 0,
  "application_fee": null,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454043073,
  "currency": "usd",
  "date": 1454043073,
  "description": null,
  "destination": "acct_17YUCRIJjRJCgHYF",
  "destination_payment": "py_17YUE1IJjRJCgHYFWBnwDP9n",
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {
  },
  "recipient": null,
  "reversals": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals"
  },
  "reversed": false,
  "source_transaction": "ch_17YUE12eZvKYlo2CxyFVzvrM",
  "source_type": "card",
  "statement_descriptor": null,
  "status": "paid",
  "type": "stripe_account"
}

Types of transfer failures

Transfers can fail for a variety of reasons. The reason a given transfer failed is available in the failure_code attribute of a Transfer object. The possible failure codes are listed below. Troubleshooting help for transfers can be found in the FAQ.

This is a list of all the types of failure codes we currently send. We may add more at any time, so you shouldn't rely on only these failure codes existing in your code.

Failure codes

  • insufficient_funds

    Your Stripe account has insufficient funds to cover the transfer.

  • account_closed

    The bank account has been closed.

  • no_account

    The bank account details on file are probably incorrect. No bank account could be located with those details.

  • invalid_account_number

    The routing number seems correct, but the account number is invalid.

  • debit_not_authorized

    Debit transactions are not approved on the bank account. Stripe requires bank accounts to be set up for both credit and debit transfers.

  • bank_ownership_changed

    The destination bank account is no longer valid because its branch has changed ownership.

  • account_frozen

    The bank account has been frozen.

  • could_not_process

    The bank could not process this transfer.

  • bank_account_restricted

    The bank account has restrictions on either the type or number of transfers allowed. This normally indicates that the bank account is a savings or other non-checking account.

  • invalid_currency

    The bank was unable to process this transfer because of its currency. This is probably because the bank account cannot accept payments in that currency.

Transfer Reversals

A previously created transfer can be reversed if it has not yet been paid out. Funds will be refunded to your available balance, and the fees you were originally charged on the transfer will be refunded. You may not reverse automatic Stripe transfers.

The transfer_reversal object

Attributes

  • id string

  • object string , value is "transfer_reversal"

  • amount integer

    Amount, in cents.

  • balance_transaction string

    Balance transaction that describes the impact on your account balance.

  • created timestamp

  • currency currency

    Three-letter ISO code representing the currency.

  • metadata #

    A set of key/value pairs that you can attach to the object. It can be useful for storing additional information in a structured format.

  • transfer string

    ID of the transfer that was reversed. 

{
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
#<Stripe::TransferReversal id=trr_103B0z2eZvKYlo2Ci7v5qs1z 0x00000a> JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
<TransferReversal transfer_reversal id=trr_103B0z2eZvKYlo2Ci7v5qs1z at 0x00000a> JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
Stripe\TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
com.stripe.model.TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
{
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
&stripe.TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}

Create a transfer reversal

When you create a new reversal, you must specify a transfer to create it on.

Creating a new reversal on a transfer that has previously been created but not paid out will return the funds to your available balance and refund the fees you were originally charged on the transfer. You may not reverse automatic Stripe transfers.

When reversing transfers to Stripe accounts, you can optionally reverse part of the transfer. You can do so as many times as you wish until the entire transfer has been reversed.

Once entirely reversed, a transfer can't be reversed again. This method will return an error when called on an already-reversed transfer, or when trying to reverse more money than is left on a transfer.

Arguments

  • id required

    The identifier of the transfer to be reversed.

  • amount optional, default is entire transfer

    A positive integer in cents representing how much of this transfer to reverse. Can only reverse up to the unreversed amount remaining of the transfer. Partial transfer reversals are only allowed for transfers to Stripe Accounts.

  • description optional, default is nullnilNonenullnullnullnull

    An arbitrary string which you can attach to a reversal object. It is displayed alongside the reversal in the dashboard. This will be unset if you POST an empty value.

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a reversal object. It can be useful for storing additional information about the reversal 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 nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

  • refund_application_fee optional, default is false

    Boolean indicating whether the application fee should be refunded when reversing this transfer. If a full transfer reversal is given, the full application fee will be refunded. Otherwise, the application fee will be refunded with an amount proportional to the amount of the transfer reversed.

Returns

Returns a transfer reversal object if the reversal succeeded. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error if the transfer has already been reversed or an invalid transfer identifier was provided. 

POST https://api.stripe.com/v1/transfers/{TRANSFER_ID}/reversals
tr = Stripe::Transfer.retrieve({TRANSFER_ID})
reversal = tr.reversals.create
tr = stripe.Transfer.retrieve({TRANSFER_ID})
re = tr.reversals.create()
$tr = \Stripe\Transfer::retrieve({TRANSFER_ID});
$re = $tr->reversals->create();
Map params = new HashMap();
Transfer tr = Transfer.retrieve({TRANSFER_ID});
Reversal re = tr.getReversals().create(params);
stripe.transfers.createReversal(
  {TRANSFER_ID},
  {},
  function(err, reversal) {
  }
);
reversal.New(&stripe.ReversalParams{Transfer: {TRANSFER_ID}})
 
curl https://api.stripe.com/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

tr = Stripe::Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C")
reversal = tr.reversals.create
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

tr = stripe.Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C")
re = tr.reversals.create()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$tr = \Stripe\Transfer::retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C");
$re = $tr->reversals->create();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> params = new HashMap<String, Object>();
Transfer tr = Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C");
Reversal re = tr.getReversals().create(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.transfers.createReversal(
  "tr_17YUE12eZvKYlo2C9i06Mk0C",
  { },
  function(err, reversal) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := reversal.New(&stripe.ReversalParams{Transfer: "tr_17YUE12eZvKYlo2C9i06Mk0C"})
 
{
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
#<Stripe::TransferReversal id=trr_103B0z2eZvKYlo2Ci7v5qs1z 0x00000a> JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
<TransferReversal transfer_reversal id=trr_103B0z2eZvKYlo2Ci7v5qs1z at 0x00000a> JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
Stripe\TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
com.stripe.model.TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
{
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
&stripe.TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_103B0z2eZvKYlo2Cm1qIPxY6",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}

Retrieve a reversal

By default, you can see the 10 most recent reversals stored directly on the transfer object, but you can also retrieve details about a specific reversal stored on the transfer.

Arguments

  • id required

    ID of reversal to retrieve.

  • transfer required

    ID of the transfer reversed.

Returns

Returns the reversal object. 

curl https://api.stripe.com/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals/trr_103B0z2eZvKYlo2Ci7v5qs1z \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

transfer = Stripe::Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C")
reversal = transfer.reversals.retrieve("trr_103B0z2eZvKYlo2Ci7v5qs1z")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

transfer = stripe.Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C")
reversal = transfer.reversals.retrieve("trr_103B0z2eZvKYlo2Ci7v5qs1z")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$transfer = \Stripe\Transfer::retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C");
$reversal = $transfer->reversals->retrieve("trr_103B0z2eZvKYlo2Ci7v5qs1z");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Transfer tr = Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C");
Reversal reversal = tr.getReversals().retrieve("trr_103B0z2eZvKYlo2Ci7v5qs1z");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.transfers.retrieveReversal(
  "tr_17YUE12eZvKYlo2C9i06Mk0C",
  "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  function(err, reversal) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := reversal.Get(
  "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  &stripe.ReversalParams{Transfer: "tr_17YUE12eZvKYlo2C9i06Mk0C"},
)
 
{
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
#<Stripe::TransferReversal id=trr_103B0z2eZvKYlo2Ci7v5qs1z 0x00000a> JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
<TransferReversal transfer_reversal id=trr_103B0z2eZvKYlo2Ci7v5qs1z at 0x00000a> JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
Stripe\TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
com.stripe.model.TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
{
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
&stripe.TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}

Update a reversal

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

This request only accepts metadata and description as arguments.

Arguments

  • description optional, default is nullnilNonenullnullnullnull

    An arbitrary string which you can attach to a reversal object. It is displayed when in the web interface alongside the reversal. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a reversal object. It can be useful for storing additional information about the reversal 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 nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

Returns

Returns the reversal object if the update succeeded. This call will returnraiseraisethrowthrowthrowreturn an an error if update parameters are invalid. 

POST https://api.stripe.com/v1/transfers/{TRANSFER_ID}/reversals/{REVERSAL_ID}
transfer = Stripe::Transfer.retrieve({TRANSFER_ID})
reversal = transfer.reversals.retrieve({REVERSAL_ID})
reversal.metadata[{KEY}] = {VALUE}
reversal.save
transfer = stripe.Transfer.retrieve({TRANSFER_ID})
reversal = transfer.reversals.retrieve({REVERSAL_ID})
reversal.metadata[{KEY}] = {VALUE}
reversal.save()
$transfer = \Stripe\Transfer::retrieve({TRANSFER_ID});
$reversal = $transfer->reversals->retrieve({REVERSAL_ID});
$reversal->metadata[{KEY}] = {VALUE};
$reversal->save();
Transfer tr = Transfer.retrieve({TRANSFER_ID});
Reversal reversal = cu.getReversals().retrieve({REVERSAL_ID});
Map metadata = new HashMap();
metdata.put({KEY}, {VALUE});
Map params = new HashMap();
params.put("metadata", metadata);
reversal.update(params);
stripe.transfers.updateReversal({TRANSFER_ID}, {REVERSAL_ID}, {
  metadata: {{KEY}: {VALUE}}
})
reversal.Update({REVERSAL_ID}, &stripe.ReversalParams{
  Transfer: {TRANSFER_ID}
  Meta: map[string]string{{KEY}: {VALUE}}
})
 
curl https://api.stripe.com/v1/transfers/tr_103B0z2eZvKYlo2CxQtyDGma/reversals/trr_103B0z2eZvKYlo2Ci7v5qs1z \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

tr = Stripe::Transfer.retrieve("tr_103B0z2eZvKYlo2CxQtyDGma")
re = tr.reversals.retrieve("trr_103B0z2eZvKYlo2Ci7v5qs1z")
re.metadata["key"] = "value"
re.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

tr = stripe.Transfer.retrieve("tr_103B0z2eZvKYlo2CxQtyDGma")
re = tr.reversals.retrieve("trr_103B0z2eZvKYlo2Ci7v5qs1z")
re.metadata["key"] = "value"
re.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$tr = \Stripe\Transfer::retrieve("tr_103B0z2eZvKYlo2CxQtyDGma");
$re = $tr->reversals->retrieve("trr_103B0z2eZvKYlo2Ci7v5qs1z");
$re->metadata["key"] = "value";
$re->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Transfer tr = Transfer.retrieve("tr_103B0z2eZvKYlo2CxQtyDGma");
Reversal re = tr.getReversals().retrieve("trr_103B0z2eZvKYlo2Ci7v5qs1z");
Map<String, String> metadata = new HashMap<String, String>();
metadata.put("key", "value");
Map<String, Object> params = new HashMap<String, Object>();
params.put("metadata", metadata);
re.update(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.transfers.updateReversal(
  "tr_103B0z2eZvKYlo2CxQtyDGma",
  "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  { metadata: { key: "value"} },
  function(err, reversal) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ref, err := reversal.Update(
  "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  &stripe.ReversalParams{
    Transfer: "tr_103B0z2eZvKYlo2CxQtyDGma",
    Meta: map[string]string{ "key": "value" }
  })
 
{
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
#<Stripe::TransferReversal id=trr_103B0z2eZvKYlo2Ci7v5qs1z 0x00000a> JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
<TransferReversal transfer_reversal id=trr_103B0z2eZvKYlo2Ci7v5qs1z at 0x00000a> JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
Stripe\TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
com.stripe.model.TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
{
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}
&stripe.TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
    "key": "value"
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}

List all reversals

You can see a list of the reversals belonging to a specific transfer. Note that the 10 most recent reversals are always available by default on the transfer object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional reversals.

Arguments

  • id required

    The ID of the transfer whose reversals 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

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

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

GET https://api.stripe.com/v1/transfers/{TRANSFER_ID}/reversals
Stripe::Transfer.retrieve({TRANSFER_ID}).reversals.all
stripe.Transfer.retrieve({TRANSFER_ID}).reversals.all()
\Stripe\Transfer::retrieve({TRANSFER_ID})->reversals->all();
Transfer.retrieve({TRANSFER_ID}).getReversals().all();
stripe.transfers.listReversals(
  {TRANSFER_ID},
  function(err, list) {...}
);
reversal.List(&stripe.ReversalListParams{Transfer: {TRANSFER_ID}})
 
curl https://api.stripe.com/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C").reversals.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C").reversals.all(
  limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Transfer::retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C")
  ->reversals->all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Transfer tr = Transfer.retrieve("tr_17YUE12eZvKYlo2C9i06Mk0C");
Map<String, Object> reversalParams = new HashMap<String, Object>();
reversalParams.put("limit", 3);
TransferReversalCollection reversals = tr.getReversals().all(reversalParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.transfers.listReversals(
  "tr_17YUE12eZvKYlo2C9i06Mk0C",
  function(err, reversals) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ReversalListParams{Transfer: "tr_17YUE12eZvKYlo2C9i06Mk0C"}
params.Filters.AddFilter("limit", "", "3")
i := reversal.List(params)
for i.Next() {
  r := i.Reversal()
}
 
{
  "object": "list",
  "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals",
  "has_more": false,
  "data": [
    {
      "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
      "object": "transfer_reversal",
      "amount": 1880,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1387829171,
      "currency": "usd",
      "metadata": {
      },
      "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals",
  "has_more": false,
  "data": [
    #<Stripe::TransferReversal id=trr_103B0z2eZvKYlo2Ci7v5qs1z 0x00000a> JSON: {
      "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
      "object": "transfer_reversal",
      "amount": 1880,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1387829171,
      "currency": "usd",
      "metadata": {
      },
      "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
    },
    #<Stripe::Reversal[...] ...>,
    #<Stripe::Reversal[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals",
  has_more: false,
  data: [
    <TransferReversal transfer_reversal id=trr_103B0z2eZvKYlo2Ci7v5qs1z at 0x00000a> JSON: {
      "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
      "object": "transfer_reversal",
      "amount": 1880,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1387829171,
      "currency": "usd",
      "metadata": {
      },
      "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
    },
    <stripe.Reversal[...] ...>,
    <stripe.Reversal[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals",
  "has_more" => false,
  "data" => [
    [0] => Stripe\TransferReversal JSON: {
      "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
      "object": "transfer_reversal",
      "amount": 1880,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1387829171,
      "currency": "usd",
      "metadata": {
      },
      "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
    }
    [1] => <Stripe\Reversal[...] ...>
    [2] => <Stripe\Reversal[...] ...>
  ]
}
#<com.stripe.model.ReversalCollection id=#> JSON: {
  "data": [
    com.stripe.model.TransferReversal JSON: {
      "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
      "object": "transfer_reversal",
      "amount": 1880,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1387829171,
      "currency": "usd",
      "metadata": {
      },
      "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
    },
    #<com.stripe.model.Reversal[...] ...>,
    #<com.stripe.model.Reversal[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/transfers/tr_17YUE12eZvKYlo2C9i06Mk0C/reversals",
  "has_more": false,
  "data": [
    {
      "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
      "object": "transfer_reversal",
      "amount": 1880,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1387829171,
      "currency": "usd",
      "metadata": {
      },
      "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
    },
    {...},
    {...}
  ]
}
&stripe.TransferReversal JSON: {
  "id": "trr_103B0z2eZvKYlo2Ci7v5qs1z",
  "object": "transfer_reversal",
  "amount": 1880,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1387829171,
  "currency": "usd",
  "metadata": {
  },
  "transfer": "tr_103B0z2eZvKYlo2CxQtyDGma"
}

Account

This is an object representing your Stripe account. You can retrieve it to see properties on the account like its current e-mail address or if the account is enabled yet to make live charges.

Some properties, marked as "managed accounts only", are only available to platforms who want to create and manage Stripe accounts.

The account object

Attributes

  • id string

    A unique identifier for the account

  • object string , value is "account"

  • business_name string

    The publicly visible name of the business

  • business_primary_color string

    A CSS hex color value representing the primary branding color for this account

  • business_url string

    The publicly visible website of the business

  • charges_enabled boolean

    Whether or not the account can create live charges

  • country string

    The country of the account

  • currencies_supported array containing strings

    The currencies this account can submit when creating charges

  • debit_negative_balances managed accounts only boolean

    Whether or not Stripe will attempt to reclaim negative account balances from this account’s bank account.

  • decline_charge_on managed accounts only hash

    Account-level settings to automatically decline certain types of charges regardless of the bank’s decision.

    child attributes

    • avs_failure boolean

      Whether or not Stripe should automatically decline charges with an incorrect zip/postal code. This setting only applies if a card includes a zip code and the bank specifically marks it as failed.

    • cvc_failure boolean

      Whether or not Stripe should automatically decline charges with an incorrect CVC. This setting only applies if a card includes a CVC and the bank specifically marks it as failed.

  • default_currency string

    The currency this account has chosen to use as the default

  • details_submitted boolean

    Whether or not account details have been submitted yet. Standalone accounts cannot receive transfers before this is true.

  • display_name string

    The display name for this account. This is used on the Stripe dashboard to help you differentiate between accounts.

  • email string

    The primary user’s email address

  • external_accounts managed accounts only list

    External accounts (bank accounts and/or cards) currently attached to this account.

    child attributes

    • object string , value is "list"

    • data array

      The list contains all external accounts that have been attached to the Stripe account. These may be bank accounts or cards.

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • managed boolean

    Whether or not the account is managed by your platform. Returns null if the account was not created by a platform.

  • metadata #

  • product_description managed accounts only string

    An internal-only description of the product or service provided. This is used by Stripe in the event the account gets flagged for potential fraud.

  • statement_descriptor string

    The text that will appear on credit card statements

  • support_email string

    A publicly shareable email address that can be reached for support for this account

  • support_phone string

    The publicly visible support phone number for the business

  • support_url string

    A publicly shareable URL that can be reached for support for this account

  • timezone string

    The timezone used in the Stripe dashboard for this account. A list of possible timezone values is maintained at the IANA Timezone Database.

  • tos_acceptance managed accounts only hash

    Who accepted the Stripe terms of service, and when they accepted it.

    child attributes

    • date timestamp

      The timestamp when the account owner accepted Stripe’s terms.

    • ip string

      The IP address from which the account owner accepted Stripe’s terms.

    • user_agent string

      The user agent of the browser from which the user accepted Stripe’s terms.

  • transfer_schedule managed accounts only hash

    When payments collected will be automatically paid out to the account holder’s bank account.

    child attributes

    • delay_days positive integer or zero

      The number of days charges for the account will be held before being paid out.

    • interval string

      How frequently funds will be paid out. One of manual (transfers only created via API call), daily, weekly, or monthly.

    • monthly_anchor positive integer or zero

      The day of the month funds will be paid out. Only shown if interval is monthly.

    • weekly_anchor string

      The day of the week funds will be paid out, of the style ‘monday’, ‘tuesday’, etc. Only shown if interval is weekly.

  • transfers_enabled boolean

    Whether or not Stripe will send automatic transfers for this account. This is only false when Stripe is waiting for additional information from the account holder.

  • verification managed accounts only hash

    The state of the account’s information requests, including what information is needed and by when it must be provided.

    child attributes

    • disabled_reason string

      A string describing the reason for this account being unable to charge and/or transfer, if that is the case. Possible values are rejected.fraud, rejected.terms_of_service, rejected.listed, rejected.other, fields_needed, listed, or other.

    • due_by timestamp

      At what time the fields_needed must be provided. If this date is in the past, the account is already in bad standing, and providing fields_needed is necessary to re-enable transfers and prevent other consequences. If this date is in the future, fields_needed must be provided to ensure the account remains in good standing.

    • fields_needed array

      Field names that need to be provided for the account to remain in good standing. Nested fields are separated by “.” (for example, “legal_entity.first_name”). 

{
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
#<Stripe::Account id=acct_1032D82eZvKYlo2C 0x00000a> JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
<Account account id=acct_1032D82eZvKYlo2C at 0x00000a> JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
Stripe\Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
com.stripe.model.Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
{
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
&stripe.Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}

Create an account

With Connect, you can create Stripe accounts for your users. To do this, you'll first need to register your platform.

Arguments

  • country optional, default is your own country

    The country the account holder resides in or that the business is legally established in. For example, if you are in the United States and the business you’re creating an account for is legally represented in Canada, you would use “CA” as the country for the account being created.

  • email required if managed is false

    The email address of the account holder. For standalone accounts, Stripe will email your user with instructions for how to set up their account. For managed accounts, this is only to make the account easier to identify to you: Stripe will never directly reach out to your users.

  • managed optional, default is false

    Whether you'd like to create a managed or standalone account. Managed accounts have extra parameters available to them, and require that you, the platform, handle all communication with the account holder. Standalone accounts are normal Stripe accounts: Stripe will email the account holder to setup a username and password, and handle all account management directly with them.

  • ...

    See account updating for more parameters you may pass. For standalone accounts, these parameters are used to pre-fill the account application we ask the account holder to fill out. For managed accounts is the information used to identify and verify the account.

Returns

Returns the account object, with an additional keys dictionaryhashdictionaryassociative arrayMapobjectmap containing secret and publishable keys for that account. 

POST https://api.stripe.com/v1/accounts
Stripe::Account.create
stripe.Account.create()
\Stripe\Account::create();
Account.create();
stripe.accounts.create();
account.New()
 
curl https://api.stripe.com/v1/accounts \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d managed=false \
   -d country=US \
   -d email="bob@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Account.create(
  :managed => false,
  :country => 'US',
  :email => 'bob@example.com'
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Account.create(
  managed=false,
  country='US',
  email='bob@example.com')
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Account::create(array(
  "managed" => false,
  "country" => "US",
  "email" => "bob@example.com"
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> accountParams = new HashMap<String, Object>();
accountParams.put("managed", false);
accountParams.put("country", 'US');
accountParams.put("email", 'bob@example.com');

Account.create(accountParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.accounts.create({
  managed: false,
  country: 'US',
  email: 'bob@example.com'
}, function(err, account) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

acc, err := account.New(&stripe.AccountParams{
  Managed: false,
  Country: "US",
  Email: "bob@example.com",
})
 
{
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "bob@example.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  },
  "keys": {
    "secret": "sk_test_Ml1A0xY2CIsqvO0bG1m34kM0",
    "publishable": "pk_test_bQu6thlpNJXSXySGaFakkLOp"
  }
}
#<Stripe::Account id=acct_1032D82eZvKYlo2C 0x00000a> JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "bob@example.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  },
  "keys": {
    "secret": "sk_test_sI6cZ8oQLyPGQvjWvLwKnBHF",
    "publishable": "pk_test_VmdpBpQdqxonDAMkOAWscktN"
  }
}
<Account account id=acct_1032D82eZvKYlo2C at 0x00000a> JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "bob@example.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  },
  "keys": {
    "secret": "sk_test_EhnWZddz8GUwr9olfD2kD5BN",
    "publishable": "pk_test_TFnJlPWpJavcH6WEmR5NHE61"
  }
}
Stripe\Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "bob@example.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  },
  "keys": {
    "secret": "sk_test_qLgmdktruWcFz2mrfqlPG4bc",
    "publishable": "pk_test_ynmM54RP19ilunMTFu4sCJiH"
  }
}
com.stripe.model.Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "bob@example.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  },
  "keys": {
    "secret": "sk_test_w8gH8cc2XSz5PAyQv6CgJge3",
    "publishable": "pk_test_3LbFVIsjswc6EhORUe3XTcPi"
  }
}
{
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "bob@example.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  },
  "keys": {
    "secret": "sk_test_awSc0qBDW0A3oUiSnDKL6YWN",
    "publishable": "pk_test_a9cPF6LKV7NXnAviNEw1ohQA"
  }
}
&stripe.Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "bob@example.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  },
  "keys": {
    "secret": "sk_test_GJtpOvIUSuYaoo3iK3uZojeU",
    "publishable": "pk_test_4IxSxpXsCWZgAXrI7qhd2sOk"
  }
}

Retrieve account details

Retrieves the details of the account.

Arguments

  • account optional

    The identifier of the account to be retrieved. If none is provided, will default to the account of the API key.

Returns

Returns an account object.

curl https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Account.retrieve("acct_1032D82eZvKYlo2C")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Account.retrieve("acct_1032D82eZvKYlo2C")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Account::retrieve("acct_1032D82eZvKYlo2C");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Account.retrieve("acct_1032D82eZvKYlo2C");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.accounts.retrieve(
  "acct_1032D82eZvKYlo2C",
  function(err, account) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

a, err := account.Get("acct_1032D82eZvKYlo2C")
 
{
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
#<Stripe::Account id=acct_1032D82eZvKYlo2C 0x00000a> JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
<Account account id=acct_1032D82eZvKYlo2C at 0x00000a> JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
Stripe\Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
com.stripe.model.Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
{
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
&stripe.Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}

Update an account

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

You may only update accounts that you manage. To update your own account, you can currently only do so via the dashboard. For more information on updating managed accounts, see our guide.

Arguments

  • business_name optional

    The publicly sharable name for this account

  • business_primary_color optional

    A CSS hex color value representing the primary branding color for this account

  • business_url optional

    The URL that best shows the service or product provided for this account

  • debit_negative_balances optional

    A boolean for whether or not Stripe should try to reclaim negative balances from the account holder’s bank account. See our managed account bank transfer guide for more information

  • decline_charge_on optional dictionaryhashdictionaryassociative arrayMapobjectmap

    Account-level settings to automatically decline certain types of charges regardless of the bank’s decision.

    child arguments

    • avs_failure optional

      Whether or not Stripe should automatically decline charges with an incorrect zip/postal code. This setting only applies if a card includes a zip code and the bank specifically marks it as failed.

    • cvc_failure optional

      Whether or not Stripe should automatically decline charges with an incorrect CVC. This setting only applies if a card includes a CVC and the bank specifically marks it as failed.

  • default_currency optional

    Three-letter ISO currency code representing the default currency for the account. This must be a currency that Stripe supports in the account’s country.

  • email optional

    Email address of the account holder. For standalone accounts, this is used to email them asking them to claim their Stripe account. For managed accounts, this is only to make the account easier to identify to you: Stripe will not email the account holder.

  • external_account optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A card or bank account to attach to the account. You can provide either a token, like the ones returned by Stripe.js, or a dictionary as documented in the external_account parameter for either card or bank account creation.

    This will create a new external account object, make it the new default external account for its currency, and delete the old default if one exists. If you want to add additional external accounts instead of replacing the existing default for this currency, use the bank account or card creation API.

    child arguments

    • object required

      The type of external account. Should be "bank_account".

    • account_number required

      The account number for the bank account in string form. Must be a checking account.

    • country required

      The country the bank account is in.

    • currency required

      The currency the bank account is in. This must be a country/currency pairing that Stripe supports.

    • account_holder_type optional

      The type of entity that holds the account. This can be either "individual" or "company". This field is required when attaching the bank account to a customer object.

    • name optional

      The name of the person or business that owns the bank account. This field is required when attaching the bank account to a customer object.

    • routing_number optional

      The routing number, sort code, or other country-appropriate institution number for the bank account. For US bank accounts, this is required and should be the ACH routing number, not the wire routing number. If you are providing an IBAN for account_number, this field is not required.

  • metadata optional

    A set of key/value pairs that you can attach to an account object. It can be useful for storing additional information about the account in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • product_description optional

    Internal-only description of the product being sold or service being provided by this account. It’s used by Stripe for risk and underwriting purposes.

  • statement_descriptor optional

    The text that will appear on credit card statements by default if a charge is being made directly on the account.

  • support_email optional

    A publicly shareable email address that can be reached for support for this account

  • support_phone optional

    A publicly shareable phone number that can be reached for support for this account

  • support_url optional

    A publicly shareable URL that can be reached for support for this account

  • tos_acceptance optional dictionaryhashdictionaryassociative arrayMapobjectmap

    Details on who accepted the Stripe terms of service, and when they accepted it. See our updating managed accounts guide for more information

    child arguments

    • date required

      The unix timestamp that Stripe’s terms of service were agreed to by the account holder

    • ip optional

      The IP address from which Stripe’s terms of service were agreed to by the account holder

    • user_agent optional

      The user agent of the browser from which Stripe’s terms of service were agreed to by the account holder

  • transfer_schedule optional dictionaryhashdictionaryassociative arrayMapobjectmap

    Details on when this account will make funds from charges available, and when they will be paid out to the account holder’s bank account. See our managed account bank transfer guide for more information

    child arguments

    • delay_days optional

      The number of days charges for the account will be held before being paid out. May also be the string “minimum” for the lowest available value (based on country). Default is “minimum”. Does not apply when interval is “manual”.

    • interval optional

      How frequently funds will be paid out. One of manual (for only triggered via API call), daily, weekly, or monthly. Default is daily.

    • monthly_anchor optional

      The day of the month funds will be paid out. Required and available only if interval is monthly.

    • weekly_anchor optional

      The day of the week funds will be paid out, of the style ‘monday’, ‘tuesday’, etc. Required and available only if interval is weekly.

Returns

Returns an account object if the call succeeded. 

POST https://api.stripe.com/v1/accounts/{ACCOUNT_ID}
account = Stripe::Account.retrieve({ACCOUNT_ID})
account.support_phone = {SUPPORT_PHONE}
...
account.save
account = stripe.Account.retrieve({ACCOUNT_ID})
account.support_phone = {SUPPORT_PHONE}
...
account.save()
$account = \Stripe\Account::retrieve({ACCOUNT_ID});
$account->support_phone = {SUPPORT_PHONE}
...
$account->save();
Account account = Account.retrieve({ACCOUNT_ID});
params.put("support_phone", {SUPPORT_PHONE});
...
account.update(params);
stripe.accounts.update({ACCOUNT_ID}, {
  support_phone: {SUPPORT_PHONE}
  ...
})
account.Update(
  {ACCOUNT_ID},
  stripe.AccountParams{
    SupportPhone: {SUPPORT_PHONE}
    ...
  }
)
 
curl https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d support_phone=555-867-5309

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

account = Stripe::Account.retrieve("acct_1032D82eZvKYlo2C")
account.support_phone = "555-867-5309"
account.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

account = stripe.Account.retrieve("acct_1032D82eZvKYlo2C")
account.support_phone = "555-867-5309"
account.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$account = \Stripe\Account::retrieve("acct_1032D82eZvKYlo2C");
$account->support_phone = "555-867-5309";
$account->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Account account = Account.retrieve("acct_1032D82eZvKYlo2C");
params.put("support_phone", "555-867-5309");
account.update(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.accounts.update("acct_1032D82eZvKYlo2C", {
  support_phone: "555-867-5309"
)
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := account.Update(
      "acct_1032D82eZvKYlo2C",
      &stripe.AccountParams{SupportPhone: "555-867-5309"},
)
 
{
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": "555-867-5309",
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
#<Stripe::Account id=acct_1032D82eZvKYlo2C 0x00000a> JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": "555-867-5309",
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
<Account account id=acct_1032D82eZvKYlo2C at 0x00000a> JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": "555-867-5309",
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
Stripe\Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": "555-867-5309",
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
com.stripe.model.Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": "555-867-5309",
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
{
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": "555-867-5309",
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}
&stripe.Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": "555-867-5309",
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}

Delete an account

With Connect, you may delete Stripe accounts you manage.

Managed accounts created using test-mode keys can be deleted at any time. Managed accounts created using live-mode keys may only be deleted once all balances are zero.

If you are looking to close your own account, use the data tab in your account settings instead.

Arguments

  • account optional

    The identifier of the account to be deleted. If none is provided, will default to the account of the API key.

Returns

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

DELETE https://api.stripe.com/v1/accounts/{ACCOUNT_ID}
account = Stripe::Account.retrieve({ACCOUNT_ID})
account.delete
account = stripe.Account.retrieve({ACCOUNT_ID})
account.delete()
$account = \Stripe\Account::retrieve({ACCOUNT_ID});
$account->delete();
Account account = Account.retrieve({ACCOUNT_ID});
account.delete();
stripe.accounts.del({ACCOUNT_ID})
account.Del({RECIPIENT_ID})
 
curl https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

account = Stripe::Account.retrieve("acct_1032D82eZvKYlo2C")
account.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

account = stripe.Account.retrieve("acct_1032D82eZvKYlo2C")
account.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$account = \Stripe\Account::retrieve("acct_1032D82eZvKYlo2C");
$account->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Account account = Account.retrieve("acct_1032D82eZvKYlo2C");
account.delete();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.accounts.del("acct_1032D82eZvKYlo2C")
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := account.Del("acct_1032D82eZvKYlo2C")
 
{
  "deleted": true,
  "id": "acct_1032D82eZvKYlo2C"
}
#<Stripe::Object id=acct_1032D82eZvKYlo2C 0x00000a> JSON: {
  "deleted": true,
  "id": "acct_1032D82eZvKYlo2C"
}
<Object object id=acct_1032D82eZvKYlo2C at 0x00000a> JSON: {
  "deleted": true,
  "id": "acct_1032D82eZvKYlo2C"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "acct_1032D82eZvKYlo2C"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "acct_1032D82eZvKYlo2C"
}
{
  "deleted": true,
  "id": "acct_1032D82eZvKYlo2C"
}
nil

List all connected accounts

Returns a list of accounts connected to your platform via Connect. If you’re not a platform, the list will be empty.

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 arrayMapobjectmap with a data property that contains an array of up to limit accounts, starting after account starting_after. Each entry in the array is a separate account object. If no more accounts are available, the resulting array will be empty.

GET https://api.stripe.com/v1/accounts
Stripe::Account.all
stripe.Account.all()
\Stripe\Account::all();
Account.all(Map<String, Object> options);
stripe.accounts.list();
account.List()
 
curl https://api.stripe.com/v1/accounts?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Account.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Account.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Account::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> accountParams = new HashMap<String, Object>();
accountParams.put("limit", 3);

Account.all(accountParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.accounts.list(
  { limit: 3 },
  function(err, accounts) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.AccountListParams{}
params.Filters.AddFilter("limit", "", "3")
i := account.List(params)
for i.Next() {
  a := i.Account()
}
 
{
  "object": "list",
  "url": "/v1/accounts",
  "has_more": false,
  "data": [
    {
      "id": "acct_1032D82eZvKYlo2C",
      "object": "account",
      "business_logo": null,
      "business_name": "Stripe.com",
      "business_url": null,
      "charges_enabled": false,
      "country": "US",
      "currencies_supported": [
        "usd",
        "aed",
        "afn",
        "..."
      ],
      "debit_negative_balances": true,
      "decline_charge_on": {
        "avs_failure": false,
        "cvc_failure": false
      },
      "default_currency": "usd",
      "details_submitted": false,
      "display_name": "Stripe.com",
      "email": "site@stripe.com",
      "external_accounts": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
      },
      "legal_entity": {
        "additional_owners": null,
        "address": {
          "city": null,
          "country": "US",
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "business_name": null,
        "business_tax_id_provided": false,
        "dob": {
          "day": null,
          "month": null,
          "year": null
        },
        "first_name": null,
        "last_name": null,
        "personal_address": {
          "city": null,
          "country": null,
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "personal_id_number_provided": false,
        "ssn_last_4_provided": false,
        "type": null,
        "verification": {
          "details": null,
          "details_code": "failed_other",
          "document": null,
          "status": "unverified"
        }
      },
      "managed": false,
      "product_description": null,
      "statement_descriptor": null,
      "support_phone": null,
      "timezone": "US/Pacific",
      "tos_acceptance": {
        "date": null,
        "ip": null,
        "user_agent": null
      },
      "transfer_schedule": {
        "delay_days": 7,
        "interval": "daily"
      },
      "transfers_enabled": false,
      "verification": {
        "disabled_reason": "fields_needed",
        "due_by": null,
        "fields_needed": [
          "business_url",
          "external_account",
          "product_description",
          "support_phone",
          "tos_acceptance.date",
          "tos_acceptance.ip"
        ]
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/accounts",
  "has_more": false,
  "data": [
    #<Stripe::Account id=acct_1032D82eZvKYlo2C 0x00000a> JSON: {
      "id": "acct_1032D82eZvKYlo2C",
      "object": "account",
      "business_logo": null,
      "business_name": "Stripe.com",
      "business_url": null,
      "charges_enabled": false,
      "country": "US",
      "currencies_supported": [
        "usd",
        "aed",
        "afn",
        "..."
      ],
      "debit_negative_balances": true,
      "decline_charge_on": {
        "avs_failure": false,
        "cvc_failure": false
      },
      "default_currency": "usd",
      "details_submitted": false,
      "display_name": "Stripe.com",
      "email": "site@stripe.com",
      "external_accounts": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
      },
      "legal_entity": {
        "additional_owners": null,
        "address": {
          "city": null,
          "country": "US",
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "business_name": null,
        "business_tax_id_provided": false,
        "dob": {
          "day": null,
          "month": null,
          "year": null
        },
        "first_name": null,
        "last_name": null,
        "personal_address": {
          "city": null,
          "country": null,
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "personal_id_number_provided": false,
        "ssn_last_4_provided": false,
        "type": null,
        "verification": {
          "details": null,
          "details_code": "failed_other",
          "document": null,
          "status": "unverified"
        }
      },
      "managed": false,
      "product_description": null,
      "statement_descriptor": null,
      "support_phone": null,
      "timezone": "US/Pacific",
      "tos_acceptance": {
        "date": null,
        "ip": null,
        "user_agent": null
      },
      "transfer_schedule": {
        "delay_days": 7,
        "interval": "daily"
      },
      "transfers_enabled": false,
      "verification": {
        "disabled_reason": "fields_needed",
        "due_by": null,
        "fields_needed": [
          "business_url",
          "external_account",
          "product_description",
          "support_phone",
          "tos_acceptance.date",
          "tos_acceptance.ip"
        ]
      }
    },
    #<Stripe::Account[...] ...>,
    #<Stripe::Account[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/accounts",
  has_more: false,
  data: [
    <Account account id=acct_1032D82eZvKYlo2C at 0x00000a> JSON: {
      "id": "acct_1032D82eZvKYlo2C",
      "object": "account",
      "business_logo": null,
      "business_name": "Stripe.com",
      "business_url": null,
      "charges_enabled": false,
      "country": "US",
      "currencies_supported": [
        "usd",
        "aed",
        "afn",
        "..."
      ],
      "debit_negative_balances": true,
      "decline_charge_on": {
        "avs_failure": false,
        "cvc_failure": false
      },
      "default_currency": "usd",
      "details_submitted": false,
      "display_name": "Stripe.com",
      "email": "site@stripe.com",
      "external_accounts": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
      },
      "legal_entity": {
        "additional_owners": null,
        "address": {
          "city": null,
          "country": "US",
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "business_name": null,
        "business_tax_id_provided": false,
        "dob": {
          "day": null,
          "month": null,
          "year": null
        },
        "first_name": null,
        "last_name": null,
        "personal_address": {
          "city": null,
          "country": null,
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "personal_id_number_provided": false,
        "ssn_last_4_provided": false,
        "type": null,
        "verification": {
          "details": null,
          "details_code": "failed_other",
          "document": null,
          "status": "unverified"
        }
      },
      "managed": false,
      "product_description": null,
      "statement_descriptor": null,
      "support_phone": null,
      "timezone": "US/Pacific",
      "tos_acceptance": {
        "date": null,
        "ip": null,
        "user_agent": null
      },
      "transfer_schedule": {
        "delay_days": 7,
        "interval": "daily"
      },
      "transfers_enabled": false,
      "verification": {
        "disabled_reason": "fields_needed",
        "due_by": null,
        "fields_needed": [
          "business_url",
          "external_account",
          "product_description",
          "support_phone",
          "tos_acceptance.date",
          "tos_acceptance.ip"
        ]
      }
    },
    <stripe.Account[...] ...>,
    <stripe.Account[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/accounts",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Account JSON: {
      "id": "acct_1032D82eZvKYlo2C",
      "object": "account",
      "business_logo": null,
      "business_name": "Stripe.com",
      "business_url": null,
      "charges_enabled": false,
      "country": "US",
      "currencies_supported": [
        "usd",
        "aed",
        "afn",
        "..."
      ],
      "debit_negative_balances": true,
      "decline_charge_on": {
        "avs_failure": false,
        "cvc_failure": false
      },
      "default_currency": "usd",
      "details_submitted": false,
      "display_name": "Stripe.com",
      "email": "site@stripe.com",
      "external_accounts": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
      },
      "legal_entity": {
        "additional_owners": null,
        "address": {
          "city": null,
          "country": "US",
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "business_name": null,
        "business_tax_id_provided": false,
        "dob": {
          "day": null,
          "month": null,
          "year": null
        },
        "first_name": null,
        "last_name": null,
        "personal_address": {
          "city": null,
          "country": null,
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "personal_id_number_provided": false,
        "ssn_last_4_provided": false,
        "type": null,
        "verification": {
          "details": null,
          "details_code": "failed_other",
          "document": null,
          "status": "unverified"
        }
      },
      "managed": false,
      "product_description": null,
      "statement_descriptor": null,
      "support_phone": null,
      "timezone": "US/Pacific",
      "tos_acceptance": {
        "date": null,
        "ip": null,
        "user_agent": null
      },
      "transfer_schedule": {
        "delay_days": 7,
        "interval": "daily"
      },
      "transfers_enabled": false,
      "verification": {
        "disabled_reason": "fields_needed",
        "due_by": null,
        "fields_needed": [
          "business_url",
          "external_account",
          "product_description",
          "support_phone",
          "tos_acceptance.date",
          "tos_acceptance.ip"
        ]
      }
    }
    [1] => <Stripe\Account[...] ...>
    [2] => <Stripe\Account[...] ...>
  ]
}
#<com.stripe.model.AccountCollection id=#> JSON: {
  "data": [
    com.stripe.model.Account JSON: {
      "id": "acct_1032D82eZvKYlo2C",
      "object": "account",
      "business_logo": null,
      "business_name": "Stripe.com",
      "business_url": null,
      "charges_enabled": false,
      "country": "US",
      "currencies_supported": [
        "usd",
        "aed",
        "afn",
        "..."
      ],
      "debit_negative_balances": true,
      "decline_charge_on": {
        "avs_failure": false,
        "cvc_failure": false
      },
      "default_currency": "usd",
      "details_submitted": false,
      "display_name": "Stripe.com",
      "email": "site@stripe.com",
      "external_accounts": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
      },
      "legal_entity": {
        "additional_owners": null,
        "address": {
          "city": null,
          "country": "US",
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "business_name": null,
        "business_tax_id_provided": false,
        "dob": {
          "day": null,
          "month": null,
          "year": null
        },
        "first_name": null,
        "last_name": null,
        "personal_address": {
          "city": null,
          "country": null,
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "personal_id_number_provided": false,
        "ssn_last_4_provided": false,
        "type": null,
        "verification": {
          "details": null,
          "details_code": "failed_other",
          "document": null,
          "status": "unverified"
        }
      },
      "managed": false,
      "product_description": null,
      "statement_descriptor": null,
      "support_phone": null,
      "timezone": "US/Pacific",
      "tos_acceptance": {
        "date": null,
        "ip": null,
        "user_agent": null
      },
      "transfer_schedule": {
        "delay_days": 7,
        "interval": "daily"
      },
      "transfers_enabled": false,
      "verification": {
        "disabled_reason": "fields_needed",
        "due_by": null,
        "fields_needed": [
          "business_url",
          "external_account",
          "product_description",
          "support_phone",
          "tos_acceptance.date",
          "tos_acceptance.ip"
        ]
      }
    },
    #<com.stripe.model.Account[...] ...>,
    #<com.stripe.model.Account[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/accounts",
  "has_more": false,
  "data": [
    {
      "id": "acct_1032D82eZvKYlo2C",
      "object": "account",
      "business_logo": null,
      "business_name": "Stripe.com",
      "business_url": null,
      "charges_enabled": false,
      "country": "US",
      "currencies_supported": [
        "usd",
        "aed",
        "afn",
        "..."
      ],
      "debit_negative_balances": true,
      "decline_charge_on": {
        "avs_failure": false,
        "cvc_failure": false
      },
      "default_currency": "usd",
      "details_submitted": false,
      "display_name": "Stripe.com",
      "email": "site@stripe.com",
      "external_accounts": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
      },
      "legal_entity": {
        "additional_owners": null,
        "address": {
          "city": null,
          "country": "US",
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "business_name": null,
        "business_tax_id_provided": false,
        "dob": {
          "day": null,
          "month": null,
          "year": null
        },
        "first_name": null,
        "last_name": null,
        "personal_address": {
          "city": null,
          "country": null,
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "personal_id_number_provided": false,
        "ssn_last_4_provided": false,
        "type": null,
        "verification": {
          "details": null,
          "details_code": "failed_other",
          "document": null,
          "status": "unverified"
        }
      },
      "managed": false,
      "product_description": null,
      "statement_descriptor": null,
      "support_phone": null,
      "timezone": "US/Pacific",
      "tos_acceptance": {
        "date": null,
        "ip": null,
        "user_agent": null
      },
      "transfer_schedule": {
        "delay_days": 7,
        "interval": "daily"
      },
      "transfers_enabled": false,
      "verification": {
        "disabled_reason": "fields_needed",
        "due_by": null,
        "fields_needed": [
          "business_url",
          "external_account",
          "product_description",
          "support_phone",
          "tos_acceptance.date",
          "tos_acceptance.ip"
        ]
      }
    },
    {...},
    {...}
  ]
}
&stripe.Account JSON: {
  "id": "acct_1032D82eZvKYlo2C",
  "object": "account",
  "business_logo": null,
  "business_name": "Stripe.com",
  "business_url": null,
  "charges_enabled": false,
  "country": "US",
  "currencies_supported": [
    "usd",
    "aed",
    "afn",
    "..."
  ],
  "debit_negative_balances": true,
  "decline_charge_on": {
    "avs_failure": false,
    "cvc_failure": false
  },
  "default_currency": "usd",
  "details_submitted": false,
  "display_name": "Stripe.com",
  "email": "site@stripe.com",
  "external_accounts": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
  },
  "legal_entity": {
    "additional_owners": null,
    "address": {
      "city": null,
      "country": "US",
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "business_name": null,
    "business_tax_id_provided": false,
    "dob": {
      "day": null,
      "month": null,
      "year": null
    },
    "first_name": null,
    "last_name": null,
    "personal_address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "personal_id_number_provided": false,
    "ssn_last_4_provided": false,
    "type": null,
    "verification": {
      "details": null,
      "details_code": "failed_other",
      "document": null,
      "status": "unverified"
    }
  },
  "managed": false,
  "product_description": null,
  "statement_descriptor": null,
  "support_phone": null,
  "timezone": "US/Pacific",
  "tos_acceptance": {
    "date": null,
    "ip": null,
    "user_agent": null
  },
  "transfer_schedule": {
    "delay_days": 7,
    "interval": "daily"
  },
  "transfers_enabled": false,
  "verification": {
    "disabled_reason": "fields_needed",
    "due_by": null,
    "fields_needed": [
      "business_url",
      "external_account",
      "product_description",
      "support_phone",
      "tos_acceptance.date",
      "tos_acceptance.ip"
    ]
  }
}

Application Fee Refunds

Application Fee Refund objects allow you to refund an application fee that has previously been created but not yet refunded. Funds will be refunded to the Stripe account that the fee was originally collected from.

The fee_refund object

Attributes

  • id string

  • object string , value is "fee_refund"

  • amount integer

    Amount, in cents.

  • balance_transaction string

    Balance transaction that describes the impact on your account balance.

  • created timestamp

  • currency currency

    Three-letter ISO code representing the currency.

  • fee string

    ID of the application fee that was refunded.

  • metadata #

    A set of key/value pairs that you can attach to the object. It can be useful for storing additional information in a structured format. 

{
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
#<Stripe::FeeRefund id=fr_7oH6Q7ahgF3ji7 0x00000a> JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
<FeeRefund fee_refund id=fr_7oH6Q7ahgF3ji7 at 0x00000a> JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
Stripe\FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
com.stripe.model.FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
{
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
&stripe.FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}

Create an application fee refund

Refunds an application fee that has previously been collected but not yet refunded. Funds will be refunded to the Stripe account that the fee was originally collected from.

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

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

Arguments

  • id required

    The identifier of the application fee to be refunded.

  • amount optional, default is entire application fee

    A positive integer in cents representing how much of this fee to refund. Can only refund up to the unrefunded amount remaining of the fee.

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund 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 nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

Returns

Returns the application fee refund object if the refund succeeded. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error if the fee has already been refunded or an invalid fee identifier was provided. 

POST https://api.stripe.com/v1/application_fees/{FEE_ID}/refunds
fee = Stripe::ApplicationFee.retrieve({FEE_ID})
fee.refund
fee = stripe.ApplicationFee.retrieve({FEE_ID})
fee.refund()
$fee = \Stripe\ApplicationFee::retrieve({FEE_ID});
$fee ->refund();
fee = ApplicationFee.retrieve({FEE_ID});
fee.refund();
stripe.applicationFees.refund({FEE_ID});
feerefund.New(&stripe.FeeRefundParams{Fee: {FEE_ID}})
 
curl https://api.stripe.com/v1/application_fees/fee_7oH66ZysNvunnF/refunds \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

fee = Stripe::ApplicationFee.retrieve("fee_7oH66ZysNvunnF")
fee.refund
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

fee = stripe.ApplicationFee.retrieve("fee_7oH66ZysNvunnF")
fee.refund()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$fee = \Stripe\ApplicationFee::retrieve("fee_7oH66ZysNvunnF");
$fee->refund();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

fee = ApplicationFee.retrieve("fee_7oH66ZysNvunnF");
fee.refund();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.applicationFees.refund(
  "fee_7oH66ZysNvunnF",
  function(err, applicationFee) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

fr, err := feerefund.New(&stripe.FeeRefundParams{Fee: "fee_7oH66ZysNvunnF")
 
{
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  },
  "refunded": true
}
#<Stripe::FeeRefund id=fr_7oH6Q7ahgF3ji7 0x00000a> JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  },
  "refunded": true
}
<FeeRefund fee_refund id=fr_7oH6Q7ahgF3ji7 at 0x00000a> JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  },
  "refunded": true
}
Stripe\FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  },
  "refunded": true
}
com.stripe.model.FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  },
  "refunded": true
}
{
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  },
  "refunded": true
}
&stripe.FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": null,
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  },
  "refunded": true
}

Retrieve an application fee refund

By default, you can see the 10 most recent refunds stored directly on the application fee object, but you can also retrieve details about a specific refund stored on the application fee.

Arguments

  • fee required

    ID of the application fee refunded.

  • id required

    ID of refund to retrieve.

Returns

Returns the application fee refund object. 

curl https://api.stripe.com/v1/application_fees/fee_7oH66ZysNvunnF/refunds/fr_7oH6Q7ahgF3ji7 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

application_fee = Stripe::ApplicationFee.retrieve("fee_7oH66ZysNvunnF")
refund = application_fee.refunds.retrieve("fr_7oH6Q7ahgF3ji7")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

application_fee = stripe.ApplicationFee.retrieve("fee_7oH66ZysNvunnF")
refund = application_fee.refunds.retrieve("fr_7oH6Q7ahgF3ji7")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$application_fee = \Stripe\ApplicationFee::retrieve("fee_7oH66ZysNvunnF");
$refund = $application_fee->refunds->retrieve("fr_7oH6Q7ahgF3ji7");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

ApplicationFee ap = ApplicationFee.retrieve("fee_7oH66ZysNvunnF");
Refund refund = ap.getRefunds().retrieve("fr_7oH6Q7ahgF3ji7");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.applicationFees.retrieveRefund(
  "fee_7oH66ZysNvunnF",
  "fr_7oH6Q7ahgF3ji7",
  function(err, refund) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := feerefund.Get(
  "fr_7oH6Q7ahgF3ji7",
  &stripe.FeeRefundParams{Fee: "fee_7oH66ZysNvunnF"}
)
 
{
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
#<Stripe::FeeRefund id=fr_7oH6Q7ahgF3ji7 0x00000a> JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
<FeeRefund fee_refund id=fr_7oH6Q7ahgF3ji7 at 0x00000a> JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
Stripe\FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
com.stripe.model.FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
{
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}
&stripe.FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}

Update an application fee refund

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

This request only accepts metadata as an argument.

Arguments

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to an application fee refund object. It can be useful for storing additional information about the refund 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 nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

Returns

Returns the application fee refund object if the update succeeded. This call will returnraiseraisethrowthrowthrowreturn an an error if update parameters are invalid. 

POST https://api.stripe.com/v1/application_fees/{FEE_ID}/refunds/{REFUND_ID}
fee = Stripe::ApplicationFee.retrieve({FEE_ID})
refund = fee.refunds.retrieve({REFUND_ID})
refund.metadata[{KEY}] = {VALUE}
refund.save
fee = stripe.ApplicationFee.retrieve({FEE_ID})
refund = fee.refunds.retrieve({REFUND_ID})
refund.metadata[{KEY}] = {VALUE}
refund.save()
$fee = \Stripe\ApplicationFee::retrieve({FEE_ID});
$refund = $fee->refunds->retrieve({REFUND_ID});
$refund->metadata[{KEY}] = {VALUE};
$refund->save();
ApplicationFee fee = ApplicationFee.retrieve({FEE_ID});
Refund refund = fee.getRefunds().retrieve({REFUND_ID});
Map metadata = new HashMap();
metdata.put({KEY}, {VALUE});
Map params = new HashMap();
params.put("metadata", metadata);
refund.update(params);
stripe.fees.updateRefund({FEE_ID}, {REFUND_ID}, {
  metadata: {{KEY}: {VALUE}}
})
feerefund.Update(
  {REFUND_ID},
  &stripe.FeeRefundParams {
    Fee: {FEE_ID},
    Meta: map[string]string{{KEY}: {VALUE}}
  },
)
 
curl https://api.stripe.com/v1/application_fees/fee_7oH66ZysNvunnF/refunds/fr_7oH6Q7ahgF3ji7 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

fee = Stripe::ApplicationFee.retrieve("fee_7oH66ZysNvunnF")
re = fee.refunds.retrieve("fr_7oH6Q7ahgF3ji7")
re.metadata["key"] = "value"
re.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

fee = stripe.ApplicationFee.retrieve("fee_7oH66ZysNvunnF")
re = fee.refunds.retrieve("fr_7oH6Q7ahgF3ji7")
re.metadata["key"] = "value"
re.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$fee = \Stripe\ApplicationFee::retrieve("fee_7oH66ZysNvunnF");
$re = $fee->refunds->retrieve("fr_7oH6Q7ahgF3ji7");
$re->metadata["key"] = "value";
$re->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

ApplicationFee fee = ApplicationFee.retrieve("fee_7oH66ZysNvunnF");
Refund re = fee.getRefunds().retrieve("fr_7oH6Q7ahgF3ji7");
Map<String, String> metadata = new HashMap<String, String>();
metadata.put("key", "value");
Map<String, Object> params = new HashMap<String, Object>();
params.put("metadata", metadata);
re.update(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.fees.updateRefund(
  "fee_7oH66ZysNvunnF",
  "fr_7oH6Q7ahgF3ji7",
  { metadata: { key: "value"} },
  function(err, refund) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ref, err := feerefund.Update(
  "fr_7oH6Q7ahgF3ji7",
  &stripe.FeeRefundParams {
    Fee: "fee_7oH66ZysNvunnF",
    Meta: map[string]string{"key": "value"},
  },
)
 
{
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
    "key": "value"
  }
}
#<Stripe::FeeRefund id=fr_7oH6Q7ahgF3ji7 0x00000a> JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
    "key": "value"
  }
}
<FeeRefund fee_refund id=fr_7oH6Q7ahgF3ji7 at 0x00000a> JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
    "key": "value"
  }
}
Stripe\FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
    "key": "value"
  }
}
com.stripe.model.FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
    "key": "value"
  }
}
{
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
    "key": "value"
  }
}
&stripe.FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
    "key": "value"
  }
}

List all application fee refunds

You can see a list of the refunds belonging to a specific application fee. Note that the 10 most recent refunds are always available by default on the application fee object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional refunds.

Arguments

  • id required

    The ID of the application fee whose refunds 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

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

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

GET https://api.stripe.com/v1/application_fees/{APPLICATION_FEE_ID}/refunds
Stripe::ApplicationFee.retrieve({APPLICATION_FEE_ID}).refunds.all
stripe.ApplicationFee.retrieve({APPLICATION_FEE_ID}).refunds.all()
\Stripe\ApplicationFee::retrieve({APPLICATION_FEE_ID})->refunds->all();
ApplicationFee.retrieve({APPLICATION_FEE_ID}).getRefunds().all();
stripe.applicationFees.listRefunds(
  {APPLICATION_FEE_ID},
  function(err, list) {...}
);
feerefund.List(&stripe.FeeRefundParams{Fee: {APPLICATION_FEE_ID}})
 
curl https://api.stripe.com/v1/application_fees/fee_7oH66ZysNvunnF/refunds?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::ApplicationFee.retrieve("fee_7oH66ZysNvunnF").refunds.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.ApplicationFee.retrieve("fee_7oH66ZysNvunnF").refunds.all(
  limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\ApplicationFee::retrieve("fee_7oH66ZysNvunnF")
  ->refunds->all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

ApplicationFee ap = ApplicationFee.retrieve("fee_7oH66ZysNvunnF");
Map<String, Object> refundParams = new HashMap<String, Object>();
refundParams.put("limit", 3);
ApplicationFeeRefundCollection refunds = ap.getRefunds().all(refundParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.applicationFees.listRefunds(
  "fee_7oH66ZysNvunnF",
  function(err, refunds) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.FeeRefundListParams{Fee: "fee_7oH66ZysNvunnF"
params.Filters.AddFilter("limit", "", "3")
i := feerefund.List(params)
for i.Next() {
  ref := i.FeeRefund()
}
 
{
  "object": "list",
  "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds",
  "has_more": false,
  "data": [
    {
      "id": "fr_7oH6Q7ahgF3ji7",
      "object": "fee_refund",
      "amount": 100,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454082776,
      "currency": "usd",
      "fee": "fee_7oH66ZysNvunnF",
      "metadata": {
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds",
  "has_more": false,
  "data": [
    #<Stripe::FeeRefund id=fr_7oH6Q7ahgF3ji7 0x00000a> JSON: {
      "id": "fr_7oH6Q7ahgF3ji7",
      "object": "fee_refund",
      "amount": 100,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454082776,
      "currency": "usd",
      "fee": "fee_7oH66ZysNvunnF",
      "metadata": {
      }
    },
    #<Stripe::Refund[...] ...>,
    #<Stripe::Refund[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/application_fees/fee_7oH66ZysNvunnF/refunds",
  has_more: false,
  data: [
    <FeeRefund fee_refund id=fr_7oH6Q7ahgF3ji7 at 0x00000a> JSON: {
      "id": "fr_7oH6Q7ahgF3ji7",
      "object": "fee_refund",
      "amount": 100,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454082776,
      "currency": "usd",
      "fee": "fee_7oH66ZysNvunnF",
      "metadata": {
      }
    },
    <stripe.Refund[...] ...>,
    <stripe.Refund[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/application_fees/fee_7oH66ZysNvunnF/refunds",
  "has_more" => false,
  "data" => [
    [0] => Stripe\FeeRefund JSON: {
      "id": "fr_7oH6Q7ahgF3ji7",
      "object": "fee_refund",
      "amount": 100,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454082776,
      "currency": "usd",
      "fee": "fee_7oH66ZysNvunnF",
      "metadata": {
      }
    }
    [1] => <Stripe\Refund[...] ...>
    [2] => <Stripe\Refund[...] ...>
  ]
}
#<com.stripe.model.RefundCollection id=#> JSON: {
  "data": [
    com.stripe.model.FeeRefund JSON: {
      "id": "fr_7oH6Q7ahgF3ji7",
      "object": "fee_refund",
      "amount": 100,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454082776,
      "currency": "usd",
      "fee": "fee_7oH66ZysNvunnF",
      "metadata": {
      }
    },
    #<com.stripe.model.Refund[...] ...>,
    #<com.stripe.model.Refund[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds",
  "has_more": false,
  "data": [
    {
      "id": "fr_7oH6Q7ahgF3ji7",
      "object": "fee_refund",
      "amount": 100,
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "created": 1454082776,
      "currency": "usd",
      "fee": "fee_7oH66ZysNvunnF",
      "metadata": {
      }
    },
    {...},
    {...}
  ]
}
&stripe.FeeRefund JSON: {
  "id": "fr_7oH6Q7ahgF3ji7",
  "object": "fee_refund",
  "amount": 100,
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "created": 1454082776,
  "currency": "usd",
  "fee": "fee_7oH66ZysNvunnF",
  "metadata": {
  }
}

Application Fees

When you collect a transaction fee on top of a charge made for your user (using Stripe Connect), an application fee object is created in your account. You can list, retrieve, and refund application fees.

For more information on collecting transaction fees, see our documentation.

The application_fee object

Attributes

  • id string

  • object string , value is "application_fee"

  • account string

    ID of the Stripe account this fee was taken from.

  • amount integer

    Amount earned, in cents.

  • amount_refunded positive integer or zero

  • application string

    ID of the Connect Application that earned the fee.

  • balance_transaction string

    Balance transaction that describes the impact of this collected application fee on your account balance (not including refunds).

  • charge string

    ID of the charge that the application fee was taken from.

  • created timestamp

  • currency currency

    Three-letter ISO code representing the currency of the charge.

  • livemode boolean

  • originating_transaction string

    ID of the corresponding charge on the platform account, if this fee was the result of a charge using the destination parameter.

  • refunded boolean

    Whether or not the fee has been fully refunded. If the fee is only partially refunded, this attribute will still be false.

  • refunds list

    A list of refunds that have been applied to the fee.

    child attributes

    • object string , value is "list"

    • data list

      child attributes

      • id string

      • object string , value is "list"

      • amount integer

        Amount, in cents.

      • balance_transaction string

        Balance transaction that describes the impact on your account balance.

      • created timestamp

      • currency currency

        Three-letter ISO code representing the currency.

      • fee string

        ID of the application fee that was refunded.

      • metadata #

        A set of key/value pairs that you can attach to the object. It can be useful for storing additional information in a structured format.

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed. 

{
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
#<Stripe::ApplicationFee id=fee_7oH66ZysNvunnF 0x00000a> JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
<ApplicationFee application_fee id=fee_7oH66ZysNvunnF at 0x00000a> JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
Stripe\ApplicationFee JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
com.stripe.model.ApplicationFee JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
{
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
&stripe.ApplicationFee JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}

Retrieve an application fee

Retrieves the details of an application fee that your account has collected. The same information is returned when refunding the application fee.

Arguments

  • id required

    The identifier of the fee to be retrieved.

Returns

Returns an application fee object if a valid identifier was provided, and returnsraisesraisesthrowsthrowsthrowsreturns an error otherwise.

curl https://api.stripe.com/v1/application_fees/fee_7oH66ZysNvunnF \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::ApplicationFee.retrieve("fee_7oH66ZysNvunnF")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.ApplicationFee.retrieve("fee_7oH66ZysNvunnF")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\ApplicationFee::retrieve("fee_7oH66ZysNvunnF");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

ApplicationFee.retrieve("fee_7oH66ZysNvunnF");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.applicationFees.retrieve(
  "fee_7oH66ZysNvunnF",
  function(err, applicationFee) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

f, err := fee.Get("fee_7oH66ZysNvunnF", nil)
 
{
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
#<Stripe::ApplicationFee id=fee_7oH66ZysNvunnF 0x00000a> JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
<ApplicationFee application_fee id=fee_7oH66ZysNvunnF at 0x00000a> JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
Stripe\ApplicationFee JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
com.stripe.model.ApplicationFee JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
{
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}
&stripe.ApplicationFee JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}

List all application fees

Returns a list of application fees you’ve previously collected. The application fees are returned in sorted order, with the most recent fees appearing first.

Arguments

  • charge optional

    Only return application fees for the charge specified by this charge ID.

  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • 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 arrayMapobjectmap with a data property that contains an array of up to limit application fees, starting after application fee starting_after. Each entry in the array is a separate application fee object. If no more fees are available, the resulting array will be empty.

GET https://api.stripe.com/v1/application_fees
Stripe::ApplicationFee.all
stripe.ApplicationFee.all()
\Stripe\ApplicationFee::all();
ApplicationFee.all(Map<String, Object> options);
stripe.applicationFees.list();
fee.List()
 
curl https://api.stripe.com/v1/application_fees?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::ApplicationFee.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.ApplicationFee.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\ApplicationFee::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> applicationFeeParams = new HashMap<String, Object>();
applicationFeeParams.put("limit", 3);

Applicationfee.all(applicationFeeParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.applicationFees.list(
  { limit: 3 },
  function(err, applicationFees) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.FeeListParams{}
params.Filters.AddFilter("limit", "", "3")
i := fee.List(params)
for i.Next() {
  f := i.Fee()
}
 
{
  "object": "list",
  "url": "/v1/application_fees",
  "has_more": false,
  "data": [
    {
      "id": "fee_7oH66ZysNvunnF",
      "object": "application_fee",
      "account": "acct_1032D82eZvKYlo2C",
      "amount": 100,
      "amount_refunded": 0,
      "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "created": 1454082776,
      "currency": "usd",
      "livemode": false,
      "originating_transaction": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/application_fees",
  "has_more": false,
  "data": [
    #<Stripe::ApplicationFee id=fee_7oH66ZysNvunnF 0x00000a> JSON: {
      "id": "fee_7oH66ZysNvunnF",
      "object": "application_fee",
      "account": "acct_1032D82eZvKYlo2C",
      "amount": 100,
      "amount_refunded": 0,
      "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "created": 1454082776,
      "currency": "usd",
      "livemode": false,
      "originating_transaction": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
      }
    },
    #<Stripe::ApplicationFee[...] ...>,
    #<Stripe::ApplicationFee[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/application_fees",
  has_more: false,
  data: [
    <ApplicationFee application_fee id=fee_7oH66ZysNvunnF at 0x00000a> JSON: {
      "id": "fee_7oH66ZysNvunnF",
      "object": "application_fee",
      "account": "acct_1032D82eZvKYlo2C",
      "amount": 100,
      "amount_refunded": 0,
      "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "created": 1454082776,
      "currency": "usd",
      "livemode": false,
      "originating_transaction": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
      }
    },
    <stripe.ApplicationFee[...] ...>,
    <stripe.ApplicationFee[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/application_fees",
  "has_more" => false,
  "data" => [
    [0] => Stripe\ApplicationFee JSON: {
      "id": "fee_7oH66ZysNvunnF",
      "object": "application_fee",
      "account": "acct_1032D82eZvKYlo2C",
      "amount": 100,
      "amount_refunded": 0,
      "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "created": 1454082776,
      "currency": "usd",
      "livemode": false,
      "originating_transaction": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
      }
    }
    [1] => <Stripe\ApplicationFee[...] ...>
    [2] => <Stripe\ApplicationFee[...] ...>
  ]
}
#<com.stripe.model.ApplicationFeeCollection id=#> JSON: {
  "data": [
    com.stripe.model.ApplicationFee JSON: {
      "id": "fee_7oH66ZysNvunnF",
      "object": "application_fee",
      "account": "acct_1032D82eZvKYlo2C",
      "amount": 100,
      "amount_refunded": 0,
      "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "created": 1454082776,
      "currency": "usd",
      "livemode": false,
      "originating_transaction": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
      }
    },
    #<com.stripe.model.ApplicationFee[...] ...>,
    #<com.stripe.model.ApplicationFee[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/application_fees",
  "has_more": false,
  "data": [
    {
      "id": "fee_7oH66ZysNvunnF",
      "object": "application_fee",
      "account": "acct_1032D82eZvKYlo2C",
      "amount": 100,
      "amount_refunded": 0,
      "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
      "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
      "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
      "created": 1454082776,
      "currency": "usd",
      "livemode": false,
      "originating_transaction": null,
      "refunded": false,
      "refunds": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
      }
    },
    {...},
    {...}
  ]
}
&stripe.ApplicationFee JSON: {
  "id": "fee_7oH66ZysNvunnF",
  "object": "application_fee",
  "account": "acct_1032D82eZvKYlo2C",
  "amount": 100,
  "amount_refunded": 0,
  "application": "ca_7oH6DBc9wNzBilZuS08jfgkopXoWV52v",
  "balance_transaction": "txn_17WEDl2eZvKYlo2CxRlP8kcb",
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1454082776,
  "currency": "usd",
  "livemode": false,
  "originating_transaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/application_fees/fee_7oH66ZysNvunnF/refunds"
  }
}

Recipients Deprecated

With recipient objects, you can transfer money from your Stripe account to a third party bank account or debit card. The API allows you to create, delete, and update your recipients. You can retrieve individual recipients as well as a list of all your recipients.

Recipient objects have been deprecated in favor of Connect, specifically the much more powerful account objects. Please use them instead. If you are already using recipients, please see our migration guide for more information.

The recipient object

Attributes

  • id string

  • object string , value is "recipient"

  • active_account hash

    Hash describing the current account on the recipient, if there is one.

    child attributes

    • id string

    • object string , value is "active_account"

    • account_holder_type string

      The type of entity that holds the account. This can be either individual or company.

    • bank_name string

      Name of the bank associated with the routing number, e.g. WELLS FARGO.

    • country string

      Two-letter ISO code representing the country the bank account is located in.

    • currency currency

      Three-letter ISO currency code representing the currency paid out to the bank account.

    • fingerprint string

      Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.

    • last4 string

    • name string

      The name of the person or business that owns the bank account.

    • routing_number string

      The routing transit number for the bank account.

    • status string

      Possible values are new, validated, verified, verification_failed, or errored. A bank account that hasn’t had any activity or validation performed is new. If Stripe can determine that the bank account exists, its status will be validated. Note that there often isn’t enough information to know (e.g. for smaller credit unions), and the validation is not always run. If customer bank account verification has succeeded, the bank account status will be verified. If the verification failed for any reason, such as microdeposit failure, the status will be verification_failed. If a transfer sent to this bank account fails, we’ll set the status to errored and will not continue to send transfers until the bank details are updated.

  • cards list

    child attributes

    • object string , value is "list"

    • data list

      child attributes

      • id string

        ID of card (used in conjunction with a customer or recipient ID)

      • object string , value is "list"

      • 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, unavailable, 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, unavailable, or unchecked.

      • brand string

        Card brand. Can be Visa, American Express, MasterCard, Discover, JCB, Diners Club, or Unknown.

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

      • cvc_check string

        If a CVC was provided, results of the check: pass, fail, unavailable, or unchecked

      • dynamic_last4 string

        (For tokenized numbers only.) The last four digits of the device account number.

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

      • funding string

        Card funding type. Can be credit, debit, prepaid, or unknown

      • last4 string

      • metadata #

        A set of key/value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format.

      • name string

        Cardholder name

      • recipient string

      • tokenization_method string

        If the card number is tokenized, this is the method that was used. Can be apple_pay or android_pay.

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • created timestamp

  • default_card string

    The default card to use for creating transfers to this recipient.

  • description string

  • email string

  • livemode boolean

  • metadata #

    A set of key/value pairs that you can attach to a recipient object. It can be useful for storing additional information about the recipient in a structured format.

  • migrated_to string

    The ID of the managed account this recipient was migrated to. If set, the recipient can no longer be updated, nor can transfers be made to it: use the managed account instead.

  • name string

    Full, legal name of the recipient.

  • type string

    Type of the recipient, one of individual or corporation. 

{
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
#<Stripe::Recipient id=rp_17WVG32eZvKYlo2Cm2ybfk1n 0x00000a> JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
<Recipient recipient id=rp_17WVG32eZvKYlo2Cm2ybfk1n at 0x00000a> JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
Stripe\Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
com.stripe.model.Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
{
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
&stripe.Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}

Create a recipient

Creates a new recipient object and verifies both the recipient's identity and, if provided, the recipient's bank account information or debit card.

Arguments

  • name required

    The recipient's full, legal name. For type individual, should be in the format "First Last", "First Middle Last", or "First M Last" (no prefixes or suffixes). For corporation, the full incorporated name.

  • type required

    Type of the recipient: either individual or corporation.

  • bank_account optional, default is nullnilNonenullnullnullnull

    A bank account to attach to the recipient. You can provide either a token, like the ones returned by Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's bank account details, with the options described below.

    child parameters

    • countrycountrycountrycountrycountrycountrycountry required

      The country the bank account is in. Currently, only US is supported.

    • routing_numberrouting_numberrouting_numberrouting_numberrouting_numberrouting_numberrouting_number required

      The routing number for the bank account in string form. This should be the ACH routing number, not the wire routing number.

    • account_numberaccount_numberaccount_numberaccount_numberaccount_numberaccount_numberaccount_number required

      The account number for the bank account in string form. Must be a checking account.

  • card optional

    A US Visa or MasterCard debit card that's not prepaid to attach to the recipient. If the debit card is not valid, recipient creation will fail. You can provide either a token, like the ones returned by Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's debit card details, with the options described below. Although not all information is required, the extra info helps prevent fraud.

    child parameters

    • numbernumbernumbernumbernumbernumbernumber required

      The debit card number, as a string without any separators.

    • exp_monthexp_monthexp_monthexp_monthexp_monthexp_monthexp_month required

      Two digit number representing the card's expiration month.

    • exp_yearexp_yearexp_yearexp_yearexp_yearexp_yearexp_year required

      Two or four digit number representing the card's expiration year.

    • cvccvccvccvccvccvccvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city optional

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

    • namenamenamenamenamenamename optional

      Cardholder's full name.

  • description optional, default is nullnilNonenullnullnullnull

    An arbitrary string which you can attach to a recipient object. It is displayed alongside the recipient in the web interface.

  • email optional, default is nullnilNonenullnullnullnull

    The recipient's email address. It is displayed alongside the recipient in the web interface and can be useful for searching and tracking.

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a recipient object. It can be useful for storing additional information about the recipient in a structured format.

  • tax_id optional

    The recipient's tax ID, as a string. For type individual, the full SSN; for type corporation, the full EIN.

Returns

Returns a recipient object if the call succeeded. The returned object will have the identity verification and bank account validation results.

If a bank account has been attached to the recipient, the returned recipient object will have an active_account attribute containing the accounts's details. 

POST https://api.stripe.com/v1/recipients
Stripe::Recipient.create
stripe.Recipient.create()
\Stripe\Recipient::create();
Recipient.create();
stripe.recipients.create();
recipient.New()
 
curl https://api.stripe.com/v1/recipients \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="John Doe" \
   -d type=individual \
   -d tax_id=000000000 \
   -d email="test@example.com" \
   -d description="Recipient for John Doe"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Recipient.create(
  :name => "John Doe",
  :type => "individual"
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Recipient.create(
  name="John Doe",
  type="individual"
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Recipient::create(array(
  "name" => "John Doe",
  "type" => "individual"
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> recipientParams = new HashMap<String, Object>();
recipientParams.put("name", "John Doe");
recipientParams.put("type", "individual");

Recipient.create(recipientParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.create({
  name: "John Doe",
  type: "individual"
}, function(err, recipient) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := recipient.New(&stripe.RecipientParams{
  Name: "John Doe",
  Type: "individual",
})
 
{
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
#<Stripe::Recipient id=rp_17WVG32eZvKYlo2Cm2ybfk1n 0x00000a> JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
<Recipient recipient id=rp_17WVG32eZvKYlo2Cm2ybfk1n at 0x00000a> JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
Stripe\Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
com.stripe.model.Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
{
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
&stripe.Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}

Retrieve a recipient

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

Arguments

  • id required

    The identifier of the recipient to be retrieved.

Returns

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

curl https://api.stripe.com/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Recipient::retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.retrieve(
  "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  function(err, recipient) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := recipient.Get("rp_17WVG32eZvKYlo2Cm2ybfk1n", nil)
 
{
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
#<Stripe::Recipient id=rp_17WVG32eZvKYlo2Cm2ybfk1n 0x00000a> JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
<Recipient recipient id=rp_17WVG32eZvKYlo2Cm2ybfk1n at 0x00000a> JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
Stripe\Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
com.stripe.model.Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
{
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
&stripe.Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}

Update a recipient

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

If you update the name or tax ID, the identity verification will automatically be rerun. If you update the bank account, the bank account validation will automatically be rerun.

Arguments

  • bank_account optional, default is nullnilNonenullnullnullnull

    A bank account to attach to the recipient. You can provide either a token, like the ones returned by Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's bank account details, with the options described below.

    child parameters

    • account_numberaccount_numberaccount_numberaccount_numberaccount_numberaccount_numberaccount_number required

      The account number for the bank account in string form. Must be a checking account.

    • countrycountrycountrycountrycountrycountrycountry required

      The country the bank account is in. Currently, only US is supported.

    • routing_numberrouting_numberrouting_numberrouting_numberrouting_numberrouting_numberrouting_number required

      The routing number for the bank account in string form. This should be the ACH routing number, not the wire routing number.

  • card optional

    A US Visa or MasterCard debit card that's not prepaid to attach to the recipient. You can provide either a token, like the ones returned by Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's debit card details, with the options described below. Passing card will create a new card, make it the new recipient default card, and delete the old recipient default if one exists. If you want to add additional debit cards instead of replacing the existing default, use the card creation API. Whenever you attach a card to a recipient, Stripe will automatically validate the debit card.

    child parameters

    • exp_monthexp_monthexp_monthexp_monthexp_monthexp_monthexp_month required

      Two digit number representing the card's expiration month.

    • exp_yearexp_yearexp_yearexp_yearexp_yearexp_yearexp_year required

      Two or four digit number representing the card's expiration year.

    • numbernumbernumbernumbernumbernumbernumber required

      The debit card number, as a string without any separators.

    • cvccvccvccvccvccvccvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

    • address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city optional

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

    • namenamenamenamenamenamename optional

      Cardholder's full name.

  • default_card optional

    ID of card to make the recipient’s new default for transfers.

  • description optional, default is nullnilNonenullnullnullnull

    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 nullnilNonenullnullnullnull and then saving.

  • email optional, default is nullnilNonenullnullnullnull

    The recipient's email address. It is displayed alongside the recipient in the web interface 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 nullnilNonenullnullnullnull and then saving.

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a recipient object. It can be useful for storing additional information about the recipient 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 nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

  • name optional, default is nullnilNonenullnullnullnull

    The recipient's full, legal name. For type individual, should be in the format "First Last", "First Middle Last", or "First M Last" (no prefixes or suffixes). For corporation, the full incorporated name.

  • tax_id optional, default is nullnilNonenullnullnullnull

    The recipient's tax ID, as a string. For type individual, the full SSN; for type corporation, the full EIN.

Returns

Returns the recipient object if the update succeeded. This call will returnraiseraisethrowthrowthrowreturn an an error if update parameters are invalid. 

POST https://api.stripe.com/v1/recipients/{RECIPIENT_ID}
rp = Stripe::Recipient.retrieve({RECIPIENT_ID})
rp.description = {NEW_DESCRIPTION}
...
rp.save
rp = stripe.Recipient.retrieve({RECIPIENT_ID})
rp.description = {NEW_DESCRIPTION}
...
rp.save()
$rp = \Stripe\Recipient::retrieve({RECIPIENT_ID});
$rp->description = {NEW_DESCRIPTION};
...
$rp->save();
Recipient rp = recipient.retrieve({RECIPIENT_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", {NEW_DESCRIPTION});
...
rp.update(updateParams);
stripe.recipients.update({RECIPIENT_ID}, {
  description: {NEW_DESCRIPTION}
});
recipient.Update({RECIPIENT_ID}, &stripe.RecipientParams{Desc: {NEW_DESCRIPTION}})
 
curl https://api.stripe.com/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Recipient for test@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

rp = Stripe::Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
rp.description = "Recipient for test@example.com"
rp.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

rp = stripe.Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
rp.description = "Recipient for test@example.com"
rp.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$rp = \Stripe\Recipient::retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
$rp->description = "Recipient for test@example.com";
$rp->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", "Recipient for test@example.com");

rp.update(updateParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.update(
  "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  { description: "Recipient for test@example.com" },
  function(err, recipient) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := recipient.Update(
  "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  &stripe.RecipientParams{Desc: "Recipient for test@example.com"},
)
 
{
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "Recipient for test@example.com",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
#<Stripe::Recipient id=rp_17WVG32eZvKYlo2Cm2ybfk1n 0x00000a> JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "Recipient for test@example.com",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
<Recipient recipient id=rp_17WVG32eZvKYlo2Cm2ybfk1n at 0x00000a> JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "Recipient for test@example.com",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
Stripe\Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "Recipient for test@example.com",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
com.stripe.model.Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "Recipient for test@example.com",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
{
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "Recipient for test@example.com",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}
&stripe.Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "Recipient for test@example.com",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}

Delete a recipient

Permanently deletes a recipient. It cannot be undone.

Arguments

  • id required

    The identifier of the recipient to be deleted.

Returns

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

Unlike other objects, deleted recipients can still be retrieved through the API, in order to be able to track the history of recipients while still removing their bank account and debit card details and preventing any further operations to be performed (such as creating new transfer).

DELETE https://api.stripe.com/v1/recipients/{RECIPIENT_ID}
rp = Stripe::Recipient.retrieve({RECIPIENT_ID})
rp.delete
rp = stripe.Recipient.retrieve({RECIPIENT_ID})
rp.delete()
$rp = \Stripe\Recipient::retrieve({RECIPIENT_ID});
$rp->delete();
Recipient rp = Recipient.retrieve({RECIPIENT_ID});
rp.delete();
stripe.recipients.del({RECIPIENT_ID})
recipient.Del({RECIPIENT_ID})
 
curl https://api.stripe.com/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

rp = Stripe::Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
rp.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

rp = stripe.Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
rp.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$rp = \Stripe\Recipient::retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
$rp->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
rp.delete();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.del(
  "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  function(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := recipient.Del("rp_17WVG32eZvKYlo2Cm2ybfk1n")
 
{
  "deleted": true,
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
#<Stripe::Object id=rp_17WVG32eZvKYlo2Cm2ybfk1n 0x00000a> JSON: {
  "deleted": true,
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
<Object object id=rp_17WVG32eZvKYlo2Cm2ybfk1n at 0x00000a> JSON: {
  "deleted": true,
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
{
  "deleted": true,
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
nil

List all recipients

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

Arguments

  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

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

  • type optional

  • verified optional

    Only return recipients that are verified or unverified.

Returns

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

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

GET https://api.stripe.com/v1/recipients
Stripe::Recipient.all
stripe.Recipient.all()
\Stripe\Recipient::all();
Recipient.all(Map<String, Object> options);
stripe.recipients.list();
recipient.List()
 
curl https://api.stripe.com/v1/recipients?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Recipient.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Recipient.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Recipient::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> recipientParams = new HashMap<String, Object>();
recipientParams.put("limit", 3);

Recipient.all(recipientParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.list(
  { limit: 3 },
  function(err, recipients) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.RecipientListParams{}
params.Filters.AddFilter("limit", "", "3")
i := recipient.List(params)
for i.Next() {
  r := i.Recipient()
}
 
{
  "object": "list",
  "url": "/v1/recipients",
  "has_more": false,
  "data": [
    {
      "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
      "object": "recipient",
      "active_account": {
        "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
        "object": "bank_account",
        "account_holder_type": null,
        "bank_name": "BANK OF AMERICA, N.A.",
        "country": "US",
        "currency": "usd",
        "fingerprint": "j1CvuuIQNXSIdZuK",
        "last4": "6789",
        "name": null,
        "routing_number": "111000025",
        "status": "new"
      },
      "cards": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
      },
      "created": 1453570387,
      "default_card": null,
      "description": "A Desc",
      "email": "email2@2.com",
      "livemode": false,
      "metadata": {
      },
      "migrated_to": null,
      "name": "Bob2 Jones2",
      "type": "individual",
      "verified": true
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/recipients",
  "has_more": false,
  "data": [
    #<Stripe::Recipient id=rp_17WVG32eZvKYlo2Cm2ybfk1n 0x00000a> JSON: {
      "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
      "object": "recipient",
      "active_account": {
        "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
        "object": "bank_account",
        "account_holder_type": null,
        "bank_name": "BANK OF AMERICA, N.A.",
        "country": "US",
        "currency": "usd",
        "fingerprint": "j1CvuuIQNXSIdZuK",
        "last4": "6789",
        "name": null,
        "routing_number": "111000025",
        "status": "new"
      },
      "cards": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
      },
      "created": 1453570387,
      "default_card": null,
      "description": "A Desc",
      "email": "email2@2.com",
      "livemode": false,
      "metadata": {
      },
      "migrated_to": null,
      "name": "Bob2 Jones2",
      "type": "individual",
      "verified": true
    },
    #<Stripe::Recipient[...] ...>,
    #<Stripe::Recipient[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/recipients",
  has_more: false,
  data: [
    <Recipient recipient id=rp_17WVG32eZvKYlo2Cm2ybfk1n at 0x00000a> JSON: {
      "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
      "object": "recipient",
      "active_account": {
        "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
        "object": "bank_account",
        "account_holder_type": null,
        "bank_name": "BANK OF AMERICA, N.A.",
        "country": "US",
        "currency": "usd",
        "fingerprint": "j1CvuuIQNXSIdZuK",
        "last4": "6789",
        "name": null,
        "routing_number": "111000025",
        "status": "new"
      },
      "cards": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
      },
      "created": 1453570387,
      "default_card": null,
      "description": "A Desc",
      "email": "email2@2.com",
      "livemode": false,
      "metadata": {
      },
      "migrated_to": null,
      "name": "Bob2 Jones2",
      "type": "individual",
      "verified": true
    },
    <stripe.Recipient[...] ...>,
    <stripe.Recipient[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/recipients",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Recipient JSON: {
      "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
      "object": "recipient",
      "active_account": {
        "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
        "object": "bank_account",
        "account_holder_type": null,
        "bank_name": "BANK OF AMERICA, N.A.",
        "country": "US",
        "currency": "usd",
        "fingerprint": "j1CvuuIQNXSIdZuK",
        "last4": "6789",
        "name": null,
        "routing_number": "111000025",
        "status": "new"
      },
      "cards": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
      },
      "created": 1453570387,
      "default_card": null,
      "description": "A Desc",
      "email": "email2@2.com",
      "livemode": false,
      "metadata": {
      },
      "migrated_to": null,
      "name": "Bob2 Jones2",
      "type": "individual",
      "verified": true
    }
    [1] => <Stripe\Recipient[...] ...>
    [2] => <Stripe\Recipient[...] ...>
  ]
}
#<com.stripe.model.RecipientCollection id=#> JSON: {
  "data": [
    com.stripe.model.Recipient JSON: {
      "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
      "object": "recipient",
      "active_account": {
        "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
        "object": "bank_account",
        "account_holder_type": null,
        "bank_name": "BANK OF AMERICA, N.A.",
        "country": "US",
        "currency": "usd",
        "fingerprint": "j1CvuuIQNXSIdZuK",
        "last4": "6789",
        "name": null,
        "routing_number": "111000025",
        "status": "new"
      },
      "cards": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
      },
      "created": 1453570387,
      "default_card": null,
      "description": "A Desc",
      "email": "email2@2.com",
      "livemode": false,
      "metadata": {
      },
      "migrated_to": null,
      "name": "Bob2 Jones2",
      "type": "individual",
      "verified": true
    },
    #<com.stripe.model.Recipient[...] ...>,
    #<com.stripe.model.Recipient[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/recipients",
  "has_more": false,
  "data": [
    {
      "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
      "object": "recipient",
      "active_account": {
        "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
        "object": "bank_account",
        "account_holder_type": null,
        "bank_name": "BANK OF AMERICA, N.A.",
        "country": "US",
        "currency": "usd",
        "fingerprint": "j1CvuuIQNXSIdZuK",
        "last4": "6789",
        "name": null,
        "routing_number": "111000025",
        "status": "new"
      },
      "cards": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
      },
      "created": 1453570387,
      "default_card": null,
      "description": "A Desc",
      "email": "email2@2.com",
      "livemode": false,
      "metadata": {
      },
      "migrated_to": null,
      "name": "Bob2 Jones2",
      "type": "individual",
      "verified": true
    },
    {...},
    {...}
  ]
}
&stripe.Recipient JSON: {
  "id": "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "object": "recipient",
  "active_account": {
    "id": "ba_17WVFz2eZvKYlo2Ce9kooGUH",
    "object": "bank_account",
    "account_holder_type": null,
    "bank_name": "BANK OF AMERICA, N.A.",
    "country": "US",
    "currency": "usd",
    "fingerprint": "j1CvuuIQNXSIdZuK",
    "last4": "6789",
    "name": null,
    "routing_number": "111000025",
    "status": "new"
  },
  "cards": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards"
  },
  "created": 1453570387,
  "default_card": null,
  "description": "A Desc",
  "email": "email2@2.com",
  "livemode": false,
  "metadata": {
  },
  "migrated_to": null,
  "name": "Bob2 Jones2",
  "type": "individual",
  "verified": true
}

Alipay Accounts

An Alipay account object allows you to accept Alipay payments. Alipay account objects can only be created through Checkout—read more about how you can set up Alipay payments.

The alipay_account object

Attributes

  • id string

  • object string , value is "alipay_account"

  • created timestamp

  • customer string

  • fingerprint string

    Uniquely identifies the account and will be the same across all Alipay account objects that are linked to the same Alipay account.

  • livemode boolean

  • metadata #

    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.

  • payment_amount positive integer

    If the Alipay account object is not reusable, the exact amount that you can create a charge for.

  • payment_currency currency

    If the Alipay account object is not reusable, the exact currency that you can create a charge for.

  • reusable boolean

    True if you can create multiple payments using this account. If the account is reusable, then you can freely choose the amount of each payment.

  • used boolean

    Whether this Alipay account object has ever been used for a payment.

  • username string

    The username for the Alipay account. 

{
  "id": "aliacc_17VPBM2eZvKYlo2CvzwYl0xt",
  "object": "alipay_account",
  "created": 1453308704,
  "fingerprint": "nBWSAr7nR0RE5MlB",
  "livemode": false,
  "payment_amount": null,
  "payment_currency": null,
  "reusable": true,
  "used": true,
  "username": "maidongxi@example.com"
}
#<Stripe::AlipayAccount id=aliacc_17VPBM2eZvKYlo2CvzwYl0xt 0x00000a> JSON: {
  "id": "aliacc_17VPBM2eZvKYlo2CvzwYl0xt",
  "object": "alipay_account",
  "created": 1453308704,
  "fingerprint": "nBWSAr7nR0RE5MlB",
  "livemode": false,
  "payment_amount": null,
  "payment_currency": null,
  "reusable": true,
  "used": true,
  "username": "maidongxi@example.com"
}
<AlipayAccount alipay_account id=aliacc_17VPBM2eZvKYlo2CvzwYl0xt at 0x00000a> JSON: {
  "id": "aliacc_17VPBM2eZvKYlo2CvzwYl0xt",
  "object": "alipay_account",
  "created": 1453308704,
  "fingerprint": "nBWSAr7nR0RE5MlB",
  "livemode": false,
  "payment_amount": null,
  "payment_currency": null,
  "reusable": true,
  "used": true,
  "username": "maidongxi@example.com"
}
Stripe\AlipayAccount JSON: {
  "id": "aliacc_17VPBM2eZvKYlo2CvzwYl0xt",
  "object": "alipay_account",
  "created": 1453308704,
  "fingerprint": "nBWSAr7nR0RE5MlB",
  "livemode": false,
  "payment_amount": null,
  "payment_currency": null,
  "reusable": true,
  "used": true,
  "username": "maidongxi@example.com"
}
com.stripe.model.AlipayAccount JSON: {
  "id": "aliacc_17VPBM2eZvKYlo2CvzwYl0xt",
  "object": "alipay_account",
  "created": 1453308704,
  "fingerprint": "nBWSAr7nR0RE5MlB",
  "livemode": false,
  "payment_amount": null,
  "payment_currency": null,
  "reusable": true,
  "used": true,
  "username": "maidongxi@example.com"
}
{
  "id": "aliacc_17VPBM2eZvKYlo2CvzwYl0xt",
  "object": "alipay_account",
  "created": 1453308704,
  "fingerprint": "nBWSAr7nR0RE5MlB",
  "livemode": false,
  "payment_amount": null,
  "payment_currency": null,
  "reusable": true,
  "used": true,
  "username": "maidongxi@example.com"
}
&stripe.AlipayAccount JSON: {
  "id": "aliacc_17VPBM2eZvKYlo2CvzwYl0xt",
  "object": "alipay_account",
  "created": 1453308704,
  "fingerprint": "nBWSAr7nR0RE5MlB",
  "livemode": false,
  "payment_amount": null,
  "payment_currency": null,
  "reusable": true,
  "used": true,
  "username": "maidongxi@example.com"
}

Bank Accounts

Bank accounts are used at Stripe in two ways: as a payment method on Customer objects and as a transfer destination on Account objects for managed accounts. The accepted and required parameters are different for each context.

The bank_account object

Attributes

  • id string

  • object string , value is "bank_account"

  • account string

  • account_holder_type string

    The type of entity that holds the account. This can be either individual or company.

  • bank_name string

    Name of the bank associated with the routing number, e.g. WELLS FARGO.

  • country string

    Two-letter ISO code representing the country the bank account is located in.

  • currency currency

    Three-letter ISO currency code representing the currency paid out to the bank account.

  • default_for_currency boolean

    This indicates whether or not this bank account is the default external account for its currency.

  • fingerprint string

    Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.

  • last4 string

  • metadata #

    A set of key/value pairs that you can attach to a bank account object. It can be useful for storing additional information about the bank account in a structured format.

  • name string

    The name of the person or business that owns the bank account.

  • routing_number string

    The routing transit number for the bank account.

  • status string

    Possible values are new, validated, verified, verification_failed, or errored. A bank account that hasn’t had any activity or validation performed is new. If Stripe can determine that the bank account exists, its status will be validated. Note that there often isn’t enough information to know (e.g. for smaller credit unions), and the validation is not always run. If customer bank account verification has succeeded, the bank account status will be verified. If the verification failed for any reason, such as microdeposit failure, the status will be verification_failed. If a transfer sent to this bank account fails, we’ll set the status to errored and will not continue to send transfers until the bank details are updated. 

{
  "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
  "object": "bank_account",
  "account": "acct_1032D82eZvKYlo2C",
  "account_holder_type": "individual",
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "default_for_currency": false,
  "fingerprint": "1JWtPxqbdX5Gamtc",
  "last4": "6789",
  "metadata": {
  },
  "name": "Jane Austen",
  "routing_number": "110000000",
  "status": "new"
}
#<Stripe::BankAccount id=ba_17YeYO2eZvKYlo2CqBW3PLNM 0x00000a> JSON: {
  "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
  "object": "bank_account",
  "account": "acct_1032D82eZvKYlo2C",
  "account_holder_type": "individual",
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "default_for_currency": false,
  "fingerprint": "1JWtPxqbdX5Gamtc",
  "last4": "6789",
  "metadata": {
  },
  "name": "Jane Austen",
  "routing_number": "110000000",
  "status": "new"
}
<BankAccount bank_account id=ba_17YeYO2eZvKYlo2CqBW3PLNM at 0x00000a> JSON: {
  "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
  "object": "bank_account",
  "account": "acct_1032D82eZvKYlo2C",
  "account_holder_type": "individual",
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "default_for_currency": false,
  "fingerprint": "1JWtPxqbdX5Gamtc",
  "last4": "6789",
  "metadata": {
  },
  "name": "Jane Austen",
  "routing_number": "110000000",
  "status": "new"
}
Stripe\BankAccount JSON: {
  "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
  "object": "bank_account",
  "account": "acct_1032D82eZvKYlo2C",
  "account_holder_type": "individual",
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "default_for_currency": false,
  "fingerprint": "1JWtPxqbdX5Gamtc",
  "last4": "6789",
  "metadata": {
  },
  "name": "Jane Austen",
  "routing_number": "110000000",
  "status": "new"
}
com.stripe.model.BankAccount JSON: {
  "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
  "object": "bank_account",
  "account": "acct_1032D82eZvKYlo2C",
  "account_holder_type": "individual",
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "default_for_currency": false,
  "fingerprint": "1JWtPxqbdX5Gamtc",
  "last4": "6789",
  "metadata": {
  },
  "name": "Jane Austen",
  "routing_number": "110000000",
  "status": "new"
}
{
  "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
  "object": "bank_account",
  "account": "acct_1032D82eZvKYlo2C",
  "account_holder_type": "individual",
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "default_for_currency": false,
  "fingerprint": "1JWtPxqbdX5Gamtc",
  "last4": "6789",
  "metadata": {
  },
  "name": "Jane Austen",
  "routing_number": "110000000",
  "status": "new"
}
&stripe.BankAccount JSON: {
  "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
  "object": "bank_account",
  "account": "acct_1032D82eZvKYlo2C",
  "account_holder_type": "individual",
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "default_for_currency": false,
  "fingerprint": "1JWtPxqbdX5Gamtc",
  "last4": "6789",
  "metadata": {
  },
  "name": "Jane Austen",
  "routing_number": "110000000",
  "status": "new"
}

Create a bank account

When you create a new bank account, you must specify a Customer or a managed account to create it on.

If the bank account's owner has no other external account in the bank account's currency, the new bank account will become the default for that currency. However, if the owner already has a bank account for that currency, the new account will only become the default if the default_for_currency parameter is set to true.

Arguments

  • source | external_account required

    When adding a bank account to a customer, the parameter name is source. When adding to an account, the parameter name is external_account. The value can either be a token, like the ones returned by Stripe.js, or a dictionary containing a user’s bank account details (with the options shown below).

    child arguments

    • object required

      The type of external account. Should be "bank_account".

    • account_number required

      The account number for the bank account in string form. Must be a checking account.

    • country required

      The country the bank account is in.

    • currency required

      The currency the bank account is in. This must be a country/currency pairing that Stripe supports.

    • account_holder_type optional

      The type of entity that holds the account. This can be either "individual" or "company". This field is required when attaching the bank account to a customer object.

    • name optional

      The name of the person or business that owns the bank account. This field is required when attaching the bank account to a customer object.

    • routing_number optional

      The routing number, sort code, or other country-appropriate institution number for the bank account. For US bank accounts, this is required and should be the ACH routing number, not the wire routing number. If you are providing an IBAN for account_number, this field is not required.

  • default_for_currency optional

    If you set this to true (or if this is the first external account being added in this currency) this bank account will become the default external account for its currency.

  • metadata optional

    A set of key/value pairs that you can attach to an external account object. It can be useful for storing additional information about the external account in a structured format.

Returns

Returns the bank account object.

Retrieve a bank account

By default, you can see the 10 most recent bank accounts stored on a Customer or a managed account directly on the object, but you can also retrieve details about a specific bank account stored on the Stripe account.

Arguments

  • id required

Returns

Returns the bank account object.

Update a bank account

Updates the metadata of a bank account (belonging to a Customer or a managed account) and optionally sets it as the default for its currency. Other bank account details are not editable by design.

Arguments

  • id required

    The ID of the bank account to be updated.

  • default_for_currency optional

    If set to true, this bank account will become the default external account for its currency.

  • metadata optional

Returns

Returns the bank account object.

Delete a bank account

You can delete bank accounts from a Customer or a managed account. If a bank account is the default external account for its currency, it can only be deleted if it is the only external account for that currency, and the currency is not the Stripe account's default currency. Otherwise, you must set another external account to be the default for the currency before deleting it.

Arguments

  • id required

Returns

Returns the deleted bank account object.

List all bank accounts

You can see a list of the bank accounts belonging to a Customer or a managed account. Note that the 10 most recent external accounts are always available by default on the corresponding Stripe object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional bank accounts.

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

Returns a list of the bank accounts stored on the customer or recipient.

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

Customer 
GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources?object=bank_account
Stripe::Customer.retrieve({CUSTOMER_ID}).sources.all(:object => "bank_account")
stripe.Customer.retrieve({CUSTOMER_ID}).sources.all(object="bank_account")
\Stripe\Customer::retrieve({CUSTOMER_ID})->sources->all(array(
  "object" => "bank_account"
));
HashMap<String, Object> sourcesParams = new HashMap<String, Object>();
sourcesParams.put("object", "bank_account");
Customer.retrieve({CUSTOMER_ID}).getSources().all(sourcesParams);
stripe.customers.listSources({CUSTOMER_ID});
card.List(&stripe.BankAccountListParams{Customer: {CUSTOMER_ID}})
curl "https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/sources?object=bank_account&limit=3" \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps").sources.all(:limit => 3, :object => "bank_account")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps").sources.all(
  limit=3, object="bank_account")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps")->sources->all(array(
  'limit'=>3, 'object' => "bank_account"));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
Map<String, Object> bankAccountParams = new HashMap<String, Object>();
cardParams.put("limit", 3);
cardParams.put("object", "bank_account");
cu.getSources().all(bankAccountParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.listSources(
  "cus_7oGjJvWit3N9Ps",
  {limit: 3, object: "bank_account"},
  function(err, bank_accounts) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

// Support for this directly in Stripe's Go library is forthcoming.
{
  "object": "list",
  "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources",
  "has_more": false,
  "data": [
    {
      "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
      "object": "bank_account",
      "account": "acct_1032D82eZvKYlo2C",
      "account_holder_type": "individual",
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "currency": "usd",
      "default_for_currency": false,
      "fingerprint": "1JWtPxqbdX5Gamtc",
      "last4": "6789",
      "metadata": {
      },
      "name": "Jane Austen",
      "routing_number": "110000000",
      "status": "new",
      "customer": "cus_7oGjJvWit3N9Ps"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources",
  "has_more": false,
  "data": [
    #<Stripe::BankAccount id=ba_17YeYO2eZvKYlo2CqBW3PLNM 0x00000a> JSON: {
      "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
      "object": "bank_account",
      "account": "acct_1032D82eZvKYlo2C",
      "account_holder_type": "individual",
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "currency": "usd",
      "default_for_currency": false,
      "fingerprint": "1JWtPxqbdX5Gamtc",
      "last4": "6789",
      "metadata": {
      },
      "name": "Jane Austen",
      "routing_number": "110000000",
      "status": "new",
      "customer": "cus_7oGjJvWit3N9Ps"
    },
    #<Stripe::BankAccount[...] ...>,
    #<Stripe::BankAccount[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers/cus_7oGjJvWit3N9Ps/sources",
  has_more: false,
  data: [
    <BankAccount bank_account id=ba_17YeYO2eZvKYlo2CqBW3PLNM at 0x00000a> JSON: {
      "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
      "object": "bank_account",
      "account": "acct_1032D82eZvKYlo2C",
      "account_holder_type": "individual",
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "currency": "usd",
      "default_for_currency": false,
      "fingerprint": "1JWtPxqbdX5Gamtc",
      "last4": "6789",
      "metadata": {
      },
      "name": "Jane Austen",
      "routing_number": "110000000",
      "status": "new",
      "customer": "cus_7oGjJvWit3N9Ps"
    },
    <stripe.BankAccount[...] ...>,
    <stripe.BankAccount[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers/cus_7oGjJvWit3N9Ps/sources",
  "has_more" => false,
  "data" => [
    [0] => Stripe\BankAccount JSON: {
      "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
      "object": "bank_account",
      "account": "acct_1032D82eZvKYlo2C",
      "account_holder_type": "individual",
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "currency": "usd",
      "default_for_currency": false,
      "fingerprint": "1JWtPxqbdX5Gamtc",
      "last4": "6789",
      "metadata": {
      },
      "name": "Jane Austen",
      "routing_number": "110000000",
      "status": "new",
      "customer": "cus_7oGjJvWit3N9Ps"
    }
    [1] => <Stripe\BankAccount[...] ...>
    [2] => <Stripe\BankAccount[...] ...>
  ]
}
#<com.stripe.model.BankAccountCollection id=#> JSON: {
  "data": [
    com.stripe.model.BankAccount JSON: {
      "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
      "object": "bank_account",
      "account": "acct_1032D82eZvKYlo2C",
      "account_holder_type": "individual",
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "currency": "usd",
      "default_for_currency": false,
      "fingerprint": "1JWtPxqbdX5Gamtc",
      "last4": "6789",
      "metadata": {
      },
      "name": "Jane Austen",
      "routing_number": "110000000",
      "status": "new",
      "customer": "cus_7oGjJvWit3N9Ps"
    },
    #<com.stripe.model.BankAccount[...] ...>,
    #<com.stripe.model.BankAccount[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources",
  "has_more": false,
  "data": [
    {
      "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
      "object": "bank_account",
      "account": "acct_1032D82eZvKYlo2C",
      "account_holder_type": "individual",
      "bank_name": "STRIPE TEST BANK",
      "country": "US",
      "currency": "usd",
      "default_for_currency": false,
      "fingerprint": "1JWtPxqbdX5Gamtc",
      "last4": "6789",
      "metadata": {
      },
      "name": "Jane Austen",
      "routing_number": "110000000",
      "status": "new",
      "customer": "cus_7oGjJvWit3N9Ps"
    },
    {...},
    {...}
  ]
}
&stripe.BankAccount JSON: {
  "id": "ba_17YeYO2eZvKYlo2CqBW3PLNM",
  "object": "bank_account",
  "account": "acct_1032D82eZvKYlo2C",
  "account_holder_type": "individual",
  "bank_name": "STRIPE TEST BANK",
  "country": "US",
  "currency": "usd",
  "default_for_currency": false,
  "fingerprint": "1JWtPxqbdX5Gamtc",
  "last4": "6789",
  "metadata": {
  },
  "name": "Jane Austen",
  "routing_number": "110000000",
  "status": "new",
  "customer": "cus_7oGjJvWit3N9Ps"
}

Bitcoin Receivers

A Bitcoin receiver wraps a Bitcoin address so that a customer can push a payment to you. This guide describes how to use receivers to create Bitcoin payments.

The bitcoin_receiver object

Attributes

  • id string

  • object string , value is "bitcoin_receiver"

  • active boolean

    True when this bitcoin receiver has received a non-zero amount of bitcoin.

  • amount positive integer

    The amount of currency that you are collecting as payment.

  • amount_received positive integer or zero

    The amount of currency to which bitcoin_amount_received has been converted.

  • bitcoin_amount positive integer

    The amount of bitcoin that the customer should send to fill the receiver. The bitcoin_amount is denominated in Satoshi: there are 10^8 Satoshi in one bitcoin.

  • bitcoin_amount_received positive integer or zero

    The amount of bitcoin that has been sent by the customer to this receiver.

  • bitcoin_uri string

    This URI can be displayed to the customer as a clickable link (to activate their bitcoin client) or as a QR code (for mobile wallets).

  • created timestamp

  • currency currency

    Three-letter ISO currency code representing the currency to which the bitcoin will be converted.

  • customer string

  • description string

  • email string

    The customer’s email address, set by the API call that creates the receiver.

  • filled boolean

    This flag is initially false and updates to true when the customer sends the bitcoin_amount to this receiver.

  • inbound_address string

    A bitcoin address that is specific to this receiver. The customer can send bitcoin to this address to fill the receiver.

  • livemode boolean

  • metadata #

    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.

  • payment string

    The ID of the payment created from the receiver, if any. Hidden when viewing the receiver with a publishable key.

  • refund_address string

    The refund address for these bitcoin, if communicated by the customer.

  • transactions list

    A list with one entry for each time that the customer sent bitcoin to the receiver. Hidden when viewing the receiver with a publishable key.

    child attributes

    • object string , value is "list"

    • data list

      child attributes

      • id string

      • object string , value is "list"

      • amount positive integer

        The amount of currency that the transaction was converted to in real-time.

      • bitcoin_amount positive integer

        The amount of bitcoin contained in the transaction.

      • created timestamp

      • currency currency

        The currency to which this transaction was converted.

      • receiver string

        The receiver to which this transaction was sent.

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • uncaptured_funds boolean

    This receiver contains uncaptured funds that can be used for a payment or refunded.

  • used_for_payment boolean 

{
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
#<Stripe::BitcoinReceiver id=btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe 0x00000a> JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
<BitcoinReceiver bitcoin_receiver id=btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe at 0x00000a> JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
Stripe\BitcoinReceiver JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
com.stripe.model.BitcoinReceiver JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
{
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
&stripe.BitcoinReceiver JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}

Create a receiver

Creates a Bitcoin receiver object that can be used to accept bitcoin payments from your customer. The receiver exposes a Bitcoin address and is created with a bitcoin to USD exchange rate that is valid for 10 minutes.

Arguments

  • amount required

    The amount of currency that you will be paid.

  • currency required

    The currency to which the bitcoin will be converted. You will be paid out in this currency. Only USD is currently supported.

  • email required

    The email address of the customer.

  • description optional

  • 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 nullnilNonenullnullnullnull and then saving.

  • refund_mispayments optional

    A flag that indicates whether you would like Stripe to automatically handle refunds for any mispayments to the receiver.

Returns

Returns a Bitcoin receiver object if the call succeeded. The returned object will include the Bitcoin address of the receiver and the bitcoin amount required to fill it. The call will returnraiseraisethrowthrowthrowreturn an an error if a currency other than USD or an amount greater than $15,000.00 is specified.

POST https://api.stripe.com/v1/bitcoin/receivers
Stripe::BitcoinReceiver.create
stripe.BitcoinReceiver.create()
Stripe_BitcoinReceiver::create();
BitcoinReceiver.create();
stripe.bitcoinReceivers.create();
bitcoinreceiver.New()
 
curl https://api.stripe.com/v1/bitcoin/receivers \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=100 \
   -d currency=usd \
   -d description="Receiver for John Doe" \
   -d email="test@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::BitcoinReceiver.create(
  :amount => 100,
  :currency => "usd",
  :description => "Receiver for John Doe",
  :email => "test@example.com"
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.BitcoinReceiver.create(
  amount=100,
  currency="usd",
  description="Receiver for John Doe",
  email="test@example.com"
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_BitcoinReceiver::create(array(
  "amount" => 100,
  "currency" => "usd",
  "description" => "Receiver for John Doe",
  "email" => "test@example.com"
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> bitcoinReceiverParams = new HashMap<String, Object>();
bitcoinReceiverParams.put("amount", 100);
bitcoinReceiverParams.put("currency", "usd");
bitcoinReceiverParams.put("description", "Receiver for John Doe");
bitcoinReceiverParams.put("email", "test@example.com");

Bitcoinreceiver.create(bitcoinReceiverParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.bitcoinReceivers.create({
  amount: 100,
  currency: "usd",
  description: "Receiver for John Doe",
  email: "test@example.com"
}, function(err, receiver) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := bitcoinreceiver.New(&stripe.BitcoinReceiverParams{
  Amount: 100,
  Currency: "usd",
  Desc: "Receiver for John Doe",
  Email: "test@example.com",
})
 
{
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
#<Stripe::BitcoinReceiver id=btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe 0x00000a> JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
<BitcoinReceiver bitcoin_receiver id=btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe at 0x00000a> JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
Stripe\BitcoinReceiver JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
com.stripe.model.BitcoinReceiver JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
{
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}
&stripe.BitcoinReceiver JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false
}

Retrieve a receiver

Retrieves the Bitcoin receiver with the given ID.

Arguments

  • id required

Returns

Returns a Bitcoin receiver if a valid ID was provided. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error otherwise.

curl https://api.stripe.com/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::BitcoinReceiver.retrieve("btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.BitcoinReceiver.retrieve("btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\BitcoinReceiver::retrieve("btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

BitcoinReceiver.retrieve("btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.bitcoinReceivers.retrieve(
  "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  function(err, bitcoinReceiver) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

b, err := bitcoinreceiver.Get("btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe", nil)
 
{
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false,
  "transactions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
    "data": [
      {
        "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
        "object": "bitcoin_transaction",
        "amount": 2000,
        "bitcoin_amount": 20000000,
        "created": 1454017178,
        "currency": "usd",
        "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
      }
    ]
  }
}
#<Stripe::BitcoinReceiver id=btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe 0x00000a> JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false,
  "transactions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
    "data": [
      {
        "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
        "object": "bitcoin_transaction",
        "amount": 2000,
        "bitcoin_amount": 20000000,
        "created": 1454017178,
        "currency": "usd",
        "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
      }
    ]
  }
}
<BitcoinReceiver bitcoin_receiver id=btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe at 0x00000a> JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false,
  "transactions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
    "data": [
      {
        "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
        "object": "bitcoin_transaction",
        "amount": 2000,
        "bitcoin_amount": 20000000,
        "created": 1454017178,
        "currency": "usd",
        "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
      }
    ]
  }
}
Stripe\BitcoinReceiver JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false,
  "transactions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
    "data": [
      {
        "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
        "object": "bitcoin_transaction",
        "amount": 2000,
        "bitcoin_amount": 20000000,
        "created": 1454017178,
        "currency": "usd",
        "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
      }
    ]
  }
}
com.stripe.model.BitcoinReceiver JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false,
  "transactions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
    "data": [
      {
        "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
        "object": "bitcoin_transaction",
        "amount": 2000,
        "bitcoin_amount": 20000000,
        "created": 1454017178,
        "currency": "usd",
        "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
      }
    ]
  }
}
{
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false,
  "transactions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
    "data": [
      {
        "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
        "object": "bitcoin_transaction",
        "amount": 2000,
        "bitcoin_amount": 20000000,
        "created": 1454017178,
        "currency": "usd",
        "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
      }
    ]
  }
}
&stripe.BitcoinReceiver JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false,
  "transactions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
    "data": [
      {
        "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
        "object": "bitcoin_transaction",
        "amount": 2000,
        "bitcoin_amount": 20000000,
        "created": 1454017178,
        "currency": "usd",
        "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
      }
    ]
  }
}

List all receivers

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

Arguments

  • active optional

    Filter for active receivers.

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

  • filled optional

    Filter for filled receivers.

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

  • uncaptured_funds optional

    Filter for receivers with uncaptured funds.

Returns

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

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

GET https://api.stripe.com/v1/bitcoin/receivers
Stripe::BitcoinReceiver.all
stripe.BitcoinReceiver.all()
\Stripe\BitcoinReceiver::all();
BitcoinReceiver.all(Map<String, Object> options);
stripe.bitcoinReceivers.list();
bitcoinreceiver.List()
 
curl https://api.stripe.com/v1/bitcoin/receivers?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::BitcoinReceiver.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.BitcoinReceiver.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\BitcoinReceiver::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> bitcoinReceiverParams = new HashMap<String, Object>();
bitcoinReceiverParams.put("limit", 3);

Bitcoinreceiver.all(bitcoinReceiverParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.bitcoinReceivers.list(
  { limit: 3 },
  function(err, bitcoinReceivers) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.BitcoinreceiverListParams{}
params.Filters.AddFilter("limit", "", "3")
i := bitcoinreceiver.List(params)
for i.Next() {
  b := i.Bitcoinreceiver()
}
 
{
  "object": "list",
  "url": "/v1/bitcoin/receivers",
  "has_more": false,
  "data": [
    {
      "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
      "object": "bitcoin_receiver",
      "active": true,
      "amount": 2000,
      "amount_received": 4000,
      "bitcoin_amount": 20000000,
      "bitcoin_amount_received": 40000000,
      "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
      "created": 1454017175,
      "currency": "usd",
      "description": "2 widgets ($20.00)",
      "email": "michelle.liao.93@gmail.com",
      "filled": true,
      "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
      "livemode": false,
      "metadata": {
      },
      "refund_address": null,
      "uncaptured_funds": true,
      "used_for_payment": false,
      "transactions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
        "data": [
          {
            "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
            "object": "bitcoin_transaction",
            "amount": 2000,
            "bitcoin_amount": 20000000,
            "created": 1454017178,
            "currency": "usd",
            "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
          }
        ]
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/bitcoin/receivers",
  "has_more": false,
  "data": [
    #<Stripe::BitcoinReceiver id=btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe 0x00000a> JSON: {
      "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
      "object": "bitcoin_receiver",
      "active": true,
      "amount": 2000,
      "amount_received": 4000,
      "bitcoin_amount": 20000000,
      "bitcoin_amount_received": 40000000,
      "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
      "created": 1454017175,
      "currency": "usd",
      "description": "2 widgets ($20.00)",
      "email": "michelle.liao.93@gmail.com",
      "filled": true,
      "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
      "livemode": false,
      "metadata": {
      },
      "refund_address": null,
      "uncaptured_funds": true,
      "used_for_payment": false,
      "transactions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
        "data": [
          {
            "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
            "object": "bitcoin_transaction",
            "amount": 2000,
            "bitcoin_amount": 20000000,
            "created": 1454017178,
            "currency": "usd",
            "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
          }
        ]
      }
    },
    #<Stripe::BitcoinReceiver[...] ...>,
    #<Stripe::BitcoinReceiver[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/bitcoin/receivers",
  has_more: false,
  data: [
    <BitcoinReceiver bitcoin_receiver id=btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe at 0x00000a> JSON: {
      "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
      "object": "bitcoin_receiver",
      "active": true,
      "amount": 2000,
      "amount_received": 4000,
      "bitcoin_amount": 20000000,
      "bitcoin_amount_received": 40000000,
      "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
      "created": 1454017175,
      "currency": "usd",
      "description": "2 widgets ($20.00)",
      "email": "michelle.liao.93@gmail.com",
      "filled": true,
      "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
      "livemode": false,
      "metadata": {
      },
      "refund_address": null,
      "uncaptured_funds": true,
      "used_for_payment": false,
      "transactions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
        "data": [
          {
            "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
            "object": "bitcoin_transaction",
            "amount": 2000,
            "bitcoin_amount": 20000000,
            "created": 1454017178,
            "currency": "usd",
            "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
          }
        ]
      }
    },
    <stripe.BitcoinReceiver[...] ...>,
    <stripe.BitcoinReceiver[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/bitcoin/receivers",
  "has_more" => false,
  "data" => [
    [0] => Stripe\BitcoinReceiver JSON: {
      "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
      "object": "bitcoin_receiver",
      "active": true,
      "amount": 2000,
      "amount_received": 4000,
      "bitcoin_amount": 20000000,
      "bitcoin_amount_received": 40000000,
      "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
      "created": 1454017175,
      "currency": "usd",
      "description": "2 widgets ($20.00)",
      "email": "michelle.liao.93@gmail.com",
      "filled": true,
      "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
      "livemode": false,
      "metadata": {
      },
      "refund_address": null,
      "uncaptured_funds": true,
      "used_for_payment": false,
      "transactions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
        "data": [
          {
            "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
            "object": "bitcoin_transaction",
            "amount": 2000,
            "bitcoin_amount": 20000000,
            "created": 1454017178,
            "currency": "usd",
            "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
          }
        ]
      }
    }
    [1] => <Stripe\BitcoinReceiver[...] ...>
    [2] => <Stripe\BitcoinReceiver[...] ...>
  ]
}
#<com.stripe.model.BitcoinReceiverCollection id=#> JSON: {
  "data": [
    com.stripe.model.BitcoinReceiver JSON: {
      "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
      "object": "bitcoin_receiver",
      "active": true,
      "amount": 2000,
      "amount_received": 4000,
      "bitcoin_amount": 20000000,
      "bitcoin_amount_received": 40000000,
      "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
      "created": 1454017175,
      "currency": "usd",
      "description": "2 widgets ($20.00)",
      "email": "michelle.liao.93@gmail.com",
      "filled": true,
      "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
      "livemode": false,
      "metadata": {
      },
      "refund_address": null,
      "uncaptured_funds": true,
      "used_for_payment": false,
      "transactions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
        "data": [
          {
            "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
            "object": "bitcoin_transaction",
            "amount": 2000,
            "bitcoin_amount": 20000000,
            "created": 1454017178,
            "currency": "usd",
            "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
          }
        ]
      }
    },
    #<com.stripe.model.BitcoinReceiver[...] ...>,
    #<com.stripe.model.BitcoinReceiver[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/bitcoin/receivers",
  "has_more": false,
  "data": [
    {
      "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
      "object": "bitcoin_receiver",
      "active": true,
      "amount": 2000,
      "amount_received": 4000,
      "bitcoin_amount": 20000000,
      "bitcoin_amount_received": 40000000,
      "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
      "created": 1454017175,
      "currency": "usd",
      "description": "2 widgets ($20.00)",
      "email": "michelle.liao.93@gmail.com",
      "filled": true,
      "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
      "livemode": false,
      "metadata": {
      },
      "refund_address": null,
      "uncaptured_funds": true,
      "used_for_payment": false,
      "transactions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
        "data": [
          {
            "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
            "object": "bitcoin_transaction",
            "amount": 2000,
            "bitcoin_amount": 20000000,
            "created": 1454017178,
            "currency": "usd",
            "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
          }
        ]
      }
    },
    {...},
    {...}
  ]
}
&stripe.BitcoinReceiver JSON: {
  "id": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe",
  "object": "bitcoin_receiver",
  "active": true,
  "amount": 2000,
  "amount_received": 4000,
  "bitcoin_amount": 20000000,
  "bitcoin_amount_received": 40000000,
  "bitcoin_uri": "bitcoin:test_qctbibWSKYRzWjhRHNZz1zjw6R6X6?amount=0.20000000",
  "created": 1454017175,
  "currency": "usd",
  "description": "2 widgets ($20.00)",
  "email": "michelle.liao.93@gmail.com",
  "filled": true,
  "inbound_address": "test_qctbibWSKYRzWjhRHNZz1zjw6R6X6",
  "livemode": false,
  "metadata": {
  },
  "refund_address": null,
  "uncaptured_funds": true,
  "used_for_payment": false,
  "transactions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/bitcoin/receivers/btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe/transactions",
    "data": [
      {
        "id": "btctxn_17YNUM2eZvKYlo2CZuerRtKj",
        "object": "bitcoin_transaction",
        "amount": 2000,
        "bitcoin_amount": 20000000,
        "created": 1454017178,
        "currency": "usd",
        "receiver": "btcrcv_17YNUJ2eZvKYlo2CRWyFKtoe"
      }
    ]
  }
}

Cards

You can store multiple cards on a customer in order to charge the customer later. You can also store multiple debit cards on a recipient or a managed account in order to transfer to those cards later.

The card object

Attributes

  • id string

    ID of card (used in conjunction with a customer or recipient ID)

  • object string , value is "card"

  • account managed accounts only string

    The account this card belongs to. This attribute will not be in the card object if the card belongs to a customer or recipient instead.

  • 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, unavailable, 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, unavailable, or unchecked.

  • brand string

    Card brand. Can be Visa, American Express, MasterCard, Discover, JCB, Diners Club, or Unknown.

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

  • currency managed accounts only currency

    Only applicable on accounts (not customers or recipients). The card can be used as a transfer destination for funds in this currency.

  • customer string

    The customer that this card belongs to. This attribute will not be in the card object if the card belongs to an account or recipient instead.

  • cvc_check string

    If a CVC was provided, results of the check: pass, fail, unavailable, or unchecked

  • default_for_currency managed accounts only boolean

    Only applicable on accounts (not customers or recipients). This indicates whether or not this card is the default external account for its currency.

  • dynamic_last4 string

    (For tokenized numbers only.) The last four digits of the device account number.

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

  • funding string

    Card funding type. Can be credit, debit, prepaid, or unknown

  • last4 string

  • metadata #

    A set of key/value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format.

  • name string

    Cardholder name

  • recipient string

    The recipient that this card belongs to. This attribute will not be in the card object if the card belongs to a customer or account instead.

  • tokenization_method string

    If the card number is tokenized, this is the method that was used. Can be apple_pay or android_pay. 

{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
#<Stripe::Card id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
<Card card id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
Stripe\Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
com.stripe.model.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
&stripe.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": null,
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}

Create a card

When you create a new credit card, you must specify a customer, recipient, or managed account to create it on.

If the card's owner has no default card, then the new card will become the default. However, if the owner already has a default then it will not change. To change the default, you should either update the customer to have a new default_source, update the recipient to have a new default_card, or set default_for_currency to true when creating a card for a managed account.

Arguments

  • source | external_account required

    When adding a card to a customer, the parameter name is source. When adding to an account, the parameter name is external_account. The value 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). Stripe will automatically validate the card.

    child arguments

    • object required

      The type of payment source. Should be "card".

    • exp_month required

      Two digit number representing the card's expiration month.

    • exp_year required

      Two or four digit number representing the card's expiration year.

    • number required

      The card number, as a string without any separators.

    • address_city optional

    • address_country optional

    • address_line1 optional

    • address_line2 optional

    • address_state optional

    • address_zip optional

    • currency managed accounts only

      Required when adding a card to an account (not applicable to a customers or recipients). The card (which must be a debit card) can be used as a transfer destination for funds in this currency. Currently, the only supported currency for debit card transfers is usd.

    • cvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • default_for_currency managed accounts only

      Only applicable on accounts (not customers or recipients). If you set this to true (or if this is the first external account being added in this currency) this card will become the default external account for its currency.

    • metadata optional

      A set of key/value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format.

    • name optional

      Cardholder's full name.

  • metadata optional

    A set of key/value pairs that you can attach to a card object. It can be useful for storing additional information about the card in a structured format.

  • default_for_currency optional managed accounts only

    Only applicable on accounts (not customers or recipients). If you set this to true (or if this is the first external account being added in this currency) this card will become the default external account for its currency.

Returns

Returns the card object.

Customer Recipient 
POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources
customer = Stripe::Customer.retrieve({CUSTOMER_ID})
customer.sources.create({:source => TOKEN_ID})
customer = stripe.Customer.retrieve({CUSTOMER_ID})
customer.sources.create(source={TOKEN_ID})
$customer = \Stripe\Customer::retrieve({CUSTOMER_ID});
$customer->sources->create(array("source" => {TOKEN_ID}));
Customer cu = Customer.retrieve({CUSTOMER_ID});
Map<String, Object> params = new HashMap<String, Object>();
params.put("source", {TOKEN_ID});
cu.createCard(params);
stripe.customers.createSource({CUSTOMER_ID}, {
  source: {TOKEN_ID}
});
card.New(&stripe.CardParams{Customer: {CUSTOMER_ID}, Token: {TOKEN_ID}})
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/sources \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d source=tok_17YYPH2eZvKYlo2C8ZbpILPR

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
customer.sources.create(:source => "tok_17YYPH2eZvKYlo2C8ZbpILPR")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
customer.sources.create(source="tok_17YYPH2eZvKYlo2C8ZbpILPR")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$cu->sources->create(array("source" => "tok_17YYPH2eZvKYlo2C8ZbpILPR"));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
Map<String, Object> params = new HashMap<String, Object>();
params.put("source", "tok_17YYPH2eZvKYlo2C8ZbpILPR");
cu.createCard(params)
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.createSource(
  "cus_7oGjJvWit3N9Ps",
  {source: "tok_17YYPH2eZvKYlo2C8ZbpILPR"},
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.New(&stripe.CardParams{
  Customer: "cus_7oGjJvWit3N9Ps",
  Token: "tok_17YYPH2eZvKYlo2C8ZbpILPR",
})
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
#<Stripe::Card id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
<Card card id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
Stripe\Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
com.stripe.model.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
&stripe.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
POST https://api.stripe.com/v1/recipients/{RECIPIENT_ID}/cards
recipient = Stripe::Recipient.retrieve({RECIPIENT_ID})
recipient.cards.create({:card => TOKEN_ID})
recipient = stripe.Recipient.retrieve({RECIPIENT_ID})
recipient.cards.create(card={TOKEN_ID})
$recipient = \Stripe\Recipient::retrieve({RECIPIENT_ID});
$recipient->cards->create(array("card" => {TOKEN_ID}));
Recipient rp = Recipient.retrieve({RECIPIENT_ID});
Map<String, Object> params = new HashMap<String, Object>();
params.put("card", {TOKEN_ID});
rp.cards->create(params);
stripe.recipients.createCard({RECIPIENT_ID}, {
  card: {TOKEN_ID}
});
card.New(&stripe.CardParams{Recipient: {RECIPIENT_ID}, Token: {TOKEN_ID}})
curl https://api.stripe.com/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d card=token_id

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
recipient.cards.create(:card => "tok_17YYPH2eZvKYlo2C8ZbpILPR")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
recipient.cards.create(card="tok_17YYPH2eZvKYlo2C8ZbpILPR")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Recipient::retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
$cu->cards->create(array("card" => "tok_17YYPH2eZvKYlo2C8ZbpILPR"));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient cu = Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
Map<String, Object> params = new HashMap<String, Object>();
params.put("card", "tok_17YYPH2eZvKYlo2C8ZbpILPR");
cu.createCard(params)
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.createCard(
  "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  {card: "tok_17YYPH2eZvKYlo2C8ZbpILPR"},
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.New(&stripe.CardParams{
  Recipient: "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  Token: "tok_17YYPH2eZvKYlo2C8ZbpILPR",
}
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
#<Stripe::Card id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
<Card card id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
Stripe\Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
com.stripe.model.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
&stripe.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}

Retrieve a card

You can always see the 10 most recent cards directly on a customer, recipient, or managed account; this method lets you retrieve details about a specific card stored on the customer, recipient, or account.

Arguments

  • id required

    The ID of the card to be retrieved.

Returns

Returns the card object.

Customer Recipient 
GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources/{CARD_ID}
customer = Stripe::Customer.retrieve({CUSTOMER_ID})
card = customer.sources.retrieve({CARD_ID})
customer = stripe.Customer.retrieve({CUSTOMER_ID})
card = customer.sources.retrieve({CARD_ID})
$customer = \Stripe\Customer::retrieve({CUSTOMER_ID});
$card = $customer->sources->retrieve({CARD_ID});
Customer cu = Customer.retrieve({CUSTOMER_ID});
PaymentSource source = cu.getSources().retrieve({CARD_ID});
if (source.getObject().equals("card")) {
  Card card = (Card) source;
  // use the card!
}
stripe.customers.retrieveCard(
  {CUSTOMER_ID},
  {CARD_ID},
  function(err, obj) {...}
);
c, err := card.Get({CARD_ID}, &stripe.CardParams{Customer: {CUSTOMER_ID}})
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/sources/card_17YeWp2eZvKYlo2CrHF1xzZG \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
card = customer.sources.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
card = customer.sources.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$customer = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$card = $customer->sources->retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
PaymentSource source = cu.getSources().retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG");
if (source.getObject().equals("card")) {
  Card card = (Card) source;
  // use the card!
}
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.retrieveCard(
  "cus_7oGjJvWit3N9Ps",
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Get(
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  &stripe.CardParams{Customer: "cus_7oGjJvWit3N9Ps"},
)
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
#<Stripe::Card id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
<Card card id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
Stripe\Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
com.stripe.model.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
&stripe.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
GET https://api.stripe.com/v1/recipients/{RECIPIENT_ID}/cards/{CARD_ID}
recipient = Stripe::Recipient.retrieve({RECIPIENT_ID})
card = recipient.cards.retrieve({CARD_ID})
recipient = stripe.Recipient.retrieve({RECIPIENT_ID})
card = recipient.cards.retrieve({CARD_ID})
$recipient = \Stripe\Recipient::retrieve({RECIPIENT_ID});
$card = $recipient->cards->retrieve({CARD_ID});
Recipient re = Recipient.retrieve({RECIPIENT_ID});
Card card = re.getCards().retrieve({CARD_ID});
stripe.recipients.retrieveCard(
  {RECIPIENT_ID},
  {CARD_ID},
  function(err, obj) {...}
);
c, err := card.Get({CARD_ID}, &stripe.CardParams{Recipient: {RECIPIENT_ID}})
curl https://api.stripe.com/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards/card_17YeWp2eZvKYlo2CrHF1xzZG \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
card = recipient.cards.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
card = recipient.cards.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$recipient = \Stripe\Recipient::retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
$card = $recipient->cards->retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient re = Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
Card card = re.getCards().retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.retrieveCard(
  "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Get(
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  &stripe.CardParams{Recipient: "rp_17WVG32eZvKYlo2Cm2ybfk1n"},
)
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
#<Stripe::Card id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
<Card card id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
Stripe\Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
com.stripe.model.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
&stripe.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}

Update 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. Stripe also works directly with card networks so that your customers can continue using your service without interruption.

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

Arguments

  • id required

    The ID of the card to be updated.

  • address_city optional

  • address_country optional

  • address_line1 optional

  • address_line2 optional

  • address_state optional

  • address_zip optional

  • default_for_currency optional managed accounts only

    Only applicable on accounts (not customers or recipients). If set to true, this card will become the default external account for its currency.

  • exp_month optional

  • exp_year optional

  • metadata optional

  • name optional

Returns

Returns the card object.

Customer Recipient 
POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources/{CARD_ID}
customer = Stripe::Customer.retrieve({CUSTOMER_ID})
card = customer.sources.retrieve({CARD_ID})
card.name = {NEW_NAME}
card.save
customer = stripe.Customer.retrieve({CUSTOMER_ID})
card = customer.sources.retrieve({CARD_ID})
card.name = {NEW_NAME}
card.save()
$customer = \Stripe\Customer::retrieve({CUSTOMER_ID});
$card = $customer->sources->retrieve({CARD_ID});
$card->name = {NEW_NAME};
$card->save();
Customer cu = Customer.retrieve({CUSTOMER_ID});
PaymentSource source = cu.getSources().retrieve({CARD_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("name", {NEW_NAME});
source.update(updateParams);
stripe.customers.updateCard({CUSTOMER_ID}, {CARD_ID}, {
  name: {NEW_NAME}
})
card.Update({CARD_ID},
  &stripe.CardParams{Customer: {CUSTOMER_ID}, Name: {NEW_NAME}}
)
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/sources/card_17YeWp2eZvKYlo2CrHF1xzZG \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="Jane Austen"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
card = customer.sources.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG")
card.name = "Jane Austen"
card.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
card = customer.sources.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG")
card.name = "Jane Austen"
card.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$card = $cu->sources->retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG");
$card->name = "Jane Austen";
$card->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
PaymentSource source = cu.getSources().retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("name", "Jane Austen");
source.update(updateParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.updateCard(
  "cus_7oGjJvWit3N9Ps",
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  { name: "Jane Austen" },
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Update(
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  &stripe.CardParams{
    Customer: "cus_7oGjJvWit3N9Ps",
    Name: "Jane Austen",
  },
)
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null
}
#<Stripe::Card id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null
}
<Card card id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null
}
Stripe\Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null
}
com.stripe.model.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null
}
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null
}
&stripe.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null
}
POST https://api.stripe.com/v1/recipients/{RECIPIENT_ID}/cards/{CARD_ID}
recipient = Stripe::Recipient.retrieve({RECIPIENT_ID})
card = recipient.cards.retrieve({CARD_ID})
card.name = {NEW_NAME}
card.save
recipient = stripe.Recipient.retrieve({RECIPIENT_ID})
card = recipient.cards.retrieve({CARD_ID})
card.name = {NEW_NAME}
card.save()
$recipient = \Stripe\Recipient::retrieve({RECIPIENT_ID});
$card = $recipient->cards->retrieve({CARD_ID}));
$card->name = {NEW_NAME};
$card->save();
Recipient cu = Recipient.retrieve({RECIPIENT_ID});
Card card = cu.getCards().retrieve({CARD_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("name", {NEW_NAME});
card.update(updateParams);
stripe.recipients.updateCard({RECIPIENT_ID}, {CARD_ID}, {
  name: {NEW_NAME}
})
card.Update({CARD_ID},
  &stripe.CardParams{Recipient: {RECIPIENT_ID}, Name: {NEW_NAME}}
)
curl https://api.stripe.com/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards/card_17YeWp2eZvKYlo2CrHF1xzZG \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="Jane Austen"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
card = recipient.cards.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG")
card.name = "Jane Austen"
card.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
card = recipient.cards.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG")
card.name = "Jane Austen"
card.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$rp = \Stripe\Recipient::retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
$card = $rp->cards->retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG");
$card->name = "Jane Austen";
$card->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
Card card = rp.getCards().retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("name", "Jane Austen");
card.update(updateParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.updateCard(
  "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  { name: "Jane Austen" },
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Update(
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  &stripe.CardParams{
    Recipient: "rp_17WVG32eZvKYlo2Cm2ybfk1n",
    Name: "Jane Austen",
  },
)
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
#<Stripe::Card id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
<Card card id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
Stripe\Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
com.stripe.model.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
{
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}
&stripe.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": "Jane Austen",
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}

Delete a card

You can delete cards from a customer, recipient, or managed account.

For customers: if you delete a card that is currently the default source, then the most recently added source will become the new default. If you delete a card that is the last remaining source on the customer then the default_source attribute will become null.

For recipients: if you delete the default card, then the most recently added card will become the new default. If you delete the last remaining card on a recipient, then the default_card attribute will become null.

For accounts: if a card's default_for_currency property is true, it can only be deleted if it is the only external account for its currency, and the currency is not the Stripe account's default currency. Otherwise, before deleting the card, you must set another external account to be the default for the currency.

Note that for cards belonging to customers, 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

    The ID of the source to be deleted.

Returns

Returns the deleted card object.

Customer Recipient 
DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources/{CARD_ID}
customer = Stripe::Customer.retrieve({CUSTOMER_ID})
customer.sources.retrieve({CARD_ID}).delete()
customer = stripe.Customer.retrieve({CUSTOMER_ID})
customer.sources.retrieve({CARD_ID}).delete()
$customer = \Stripe\Customer::retrieve({CUSTOMER_ID});
$customer->sources->retrieve({CARD_ID})->delete();
Customer cu = Customer.retrieve({CUSTOMER_ID});
for(PaymentSource source : cu.getSources().getData()){
  if(source.getId().equals({CARD_ID})){
    source.delete();
    break;
  }
}
stripe.customers.deleteCard({CUSTOMER_ID}, {CARD_ID})
card.Del({CARD_ID}, &stripe.CardParams{Customer: {CUSTOMER_ID}})
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/sources/card_17YeWp2eZvKYlo2CrHF1xzZG \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
customer.sources.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG").delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
customer.sources.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG").delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$cu->sources->retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG")->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
for(PaymentSource source : cu.getSources().getData()){
  if(source.getId().equals("card_17YeWp2eZvKYlo2CrHF1xzZG")){
    source.delete();
    break;
  }
}
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.deleteCard(
  "cus_7oGjJvWit3N9Ps",
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  function(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := card.Del(
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  &stripe.CardParams{Customer: "cus_7oGjJvWit3N9Ps"},
)
{
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG"
}
#<Stripe::Object id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG"
}
<Object object id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG"
}
com.stripe.model.Deletedcard JSON: {
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "deletedcard"
}
{
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG"
}
nil
DELETE https://api.stripe.com/v1/recipients/{RECIPIENT_ID}/cards/{CARD_ID}
recipient = Stripe::Recipient.retrieve({RECIPIENT_ID})
recipient.cards.retrieve({CARD_ID}).delete
recipient = stripe.Recipient.retrieve({RECIPIENT_ID})
recipient.cards.retrieve({CARD_ID}).delete()
$recipient = \Stripe\Recipient::retrieve({RECIPIENT_ID});
$recipient->cards->retrieve({CARD_ID})->delete();
Recipient rp = Recipient.retrieve({RECIPIENT_ID});
for(Card card : rp.getCards().getData()){
  if(card.getId().equals({CARD_ID})){
    card.delete();
    break;
  }
}
stripe.recipients.deleteCard({RECIPIENT_ID}, {CARD_ID})
card.Del({CARD_ID}, &stripe.CardParams{Recipient: {RECIPIENT_ID}})
curl https://api.stripe.com/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards/card_17YeWp2eZvKYlo2CrHF1xzZG \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
recipient.cards.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG").delete()
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")
recipient.cards.retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG").delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$rp = \Stripe\Recipient::retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
$rp->cards->retrieve("card_17YeWp2eZvKYlo2CrHF1xzZG")->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
for(Card card : rp.getCards().getData()){
  if(card.getId().equals("card_17YeWp2eZvKYlo2CrHF1xzZG")){
    card.delete();
    break;
  }
}
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.deleteCard(
  "rp_17WVG32eZvKYlo2Cm2ybfk1n",
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  function(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := card.Del(
  "card_17YeWp2eZvKYlo2CrHF1xzZG",
  &stripe.CardParams{Recipient: "rp_17WVG32eZvKYlo2Cm2ybfk1n"},
)
{
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG"
}
#<Stripe::Object id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG"
}
<Object object id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG"
}
com.stripe.model.Deletedcard JSON: {
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "deletedcard"
}
{
  "deleted": true,
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG"
}
nil

List all cards

You can see a list of the cards belonging to a customer, recipient, or managed account. Note that the 10 most recent sources are always available on the customer object, and the 10 most recent external accounts are available on the account object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional cards.

Arguments

  • customer 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 cards stored on the customer, recipient, or account.

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

Customer Recipient 
GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources?object=card
Stripe::Customer.retrieve({CUSTOMER_ID}).sources.all(:object => "card")
stripe.Customer.retrieve({CUSTOMER_ID}).sources.all(object="card")
\Stripe\Customer::retrieve({CUSTOMER_ID})->sources->all(array(
  "object" => "card"
));
HashMap<String, Object> sourcesParams = new HashMap<String, Object>();
sourcesParams.put("object", "card");
Customer.retrieve({CUSTOMER_ID}).getSources().all(sourcesParams);
stripe.customers.listCards({CUSTOMER_ID});
card.List(&stripe.CardListParams{Customer: {CUSTOMER_ID})
curl "https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/sources?object=card&limit=3" \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps").sources.all(:limit => 3, :object => "card")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps").sources.all(
  limit=3, object='card')
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps")->sources->all(array(
  'limit'=>3, 'object' => 'card'));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
Map<String, Object> cardParams = new HashMap<String, Object>();
cardParams.put("limit", 3);
cardParams.put("object", "card");
cu.getSources().all(cardParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.listCards('cus_7oGjJvWit3N9Ps', function(err, cards) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CardListParams{Customer: "cus_7oGjJvWit3N9Ps"}
params.Filters.AddFilter("limit", "", "3")
i := card.List(params)
for i.Next() {
  c := i.Card()
}
{
  "object": "list",
  "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources",
  "has_more": false,
  "data": [
    {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "customer": "cus_7oGjJvWit3N9Ps",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources",
  "has_more": false,
  "data": [
    #<Stripe::Card id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "customer": "cus_7oGjJvWit3N9Ps",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null
    },
    #<Stripe::Card[...] ...>,
    #<Stripe::Card[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers/cus_7oGjJvWit3N9Ps/sources",
  has_more: false,
  data: [
    <Card card id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "customer": "cus_7oGjJvWit3N9Ps",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null
    },
    <stripe.Card[...] ...>,
    <stripe.Card[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers/cus_7oGjJvWit3N9Ps/sources",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Card JSON: {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "customer": "cus_7oGjJvWit3N9Ps",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null
    }
    [1] => <Stripe\Card[...] ...>
    [2] => <Stripe\Card[...] ...>
  ]
}
#<com.stripe.model.CardCollection id=#> JSON: {
  "data": [
    com.stripe.model.Card JSON: {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "customer": "cus_7oGjJvWit3N9Ps",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null
    },
    #<com.stripe.model.Card[...] ...>,
    #<com.stripe.model.Card[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers/cus_7oGjJvWit3N9Ps/sources",
  "has_more": false,
  "data": [
    {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "customer": "cus_7oGjJvWit3N9Ps",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null
    },
    {...},
    {...}
  ]
}
&stripe.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "cus_7oGjJvWit3N9Ps",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
GET https://api.stripe.com/v1/recipients/{RECIPIENT_ID}/cards
Stripe::Recipient.retrieve({RECIPIENT_ID}).cards.all()
stripe.Recipient.retrieve({RECIPIENT_ID}).cards.all()
\Stripe\Recipient::retrieve({RECIPIENT_ID})->cards->all();
Recipient.retrieve({RECIPIENT_ID}).getCards().all();
stripe.recipients.listCards({RECIPIENT_ID});
card.List(&stripe.CardListParams{Recipient: {RECIPIENT_ID}})
curl https://api.stripe.com/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n").cards.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n").cards.all(
  limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Recipient::retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n")->cards->all(array(
  'limit'=>3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_17WVG32eZvKYlo2Cm2ybfk1n");
Map<String, Object> cardParams = new HashMap<String, Object>();
cardParams.put("limit", 3);
RecipientCardCollection cards = rp.getCards().all(cardParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.listCards('rp_17WVG32eZvKYlo2Cm2ybfk1n', function(err, cards) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CardListParams{Recipient: "rp_17WVG32eZvKYlo2Cm2ybfk1n"}
params.Filters.AddFilter("limit", "", "3")
i := card.List(params)
for i.Next() {
  c := i.Card()
}
{
  "object": "list",
  "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards",
  "has_more": false,
  "data": [
    {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null,
      "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards",
  "has_more": false,
  "data": [
    #<Stripe::Card id=card_17YeWp2eZvKYlo2CrHF1xzZG 0x00000a> JSON: {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null,
      "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
    },
    #<Stripe::Card[...] ...>,
    #<Stripe::Card[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards",
  has_more: false,
  data: [
    <Card card id=card_17YeWp2eZvKYlo2CrHF1xzZG at 0x00000a> JSON: {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null,
      "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
    },
    <stripe.Card[...] ...>,
    <stripe.Card[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Card JSON: {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null,
      "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
    }
    [1] => <Stripe\Card[...] ...>
    [2] => <Stripe\Card[...] ...>
  ]
}
#<com.stripe.model.CardCollection id=#> JSON: {
  "data": [
    com.stripe.model.Card JSON: {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null,
      "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
    },
    #<com.stripe.model.Card[...] ...>,
    #<com.stripe.model.Card[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/recipients/rp_17WVG32eZvKYlo2Cm2ybfk1n/cards",
  "has_more": false,
  "data": [
    {
      "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "cvc_check": "unchecked",
      "dynamic_last4": null,
      "exp_month": 1,
      "exp_year": 2016,
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null,
      "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
    },
    {...},
    {...}
  ]
}
&stripe.Card JSON: {
  "id": "card_17YeWp2eZvKYlo2CrHF1xzZG",
  "object": "card",
  "address_city": null,
  "address_country": null,
  "address_line1": null,
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "cvc_check": "unchecked",
  "dynamic_last4": null,
  "exp_month": 1,
  "exp_year": 2016,
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null,
  "recipient": "rp_17WVG32eZvKYlo2Cm2ybfk1n"
}

Orders

The purchase of previously defined products by end customers is handled through the creation of order objects. You can create, retrieve, and pay individual orders, as well as list all orders. Orders are identified by a unique random ID.

The order object

Attributes

  • id string

  • object string , value is "order"

  • amount integer

    A positive integer in the smallest currency unit (that is, 100 cents for $1.00, or 1 for ¥1, Japanese Yen being a 0-decimal currency) representing the total amount for the order.

  • application string

    ID of the Connect Application that created the order.

  • application_fee integer

  • charge string

    The ID of the payment used to pay for the order. Present if the order status is paid, fulfilled, or refunded.

  • created timestamp

  • currency currency

    3-letter ISO code representing the currency in which the order was made.

  • customer string

    The customer used for the order.

  • email string

    The email address of the customer placing the order.

  • items list

    List of items constituting the order.

    child attributes

    • object string , value is "list"

    • amount integer

      A positive integer in the smallest currency unit (that is, 100 cents for $1.00, or 1 for ¥1, Japanese Yen being a 0-decimal currency) representing the total amount for the line item.

    • currency currency

      3-letter ISO code representing the currency of the line item.

    • description string

      Description of the line item, meant to be displayable to the user (e.g., "Express shipping").

    • parent string

      The ID of the associated object for this line item. Expandable if not null (e.g., expandable to a SKU).

    • quantity positive integer

      A positive integer representing the number of instances of parent that are included in this order item. Applicable/present only if type is sku.

    • type string

      The type of line item. One of sku, tax, shipping, or discount.

  • livemode boolean

  • metadata #

    A set of key/value pairs that you can attach to an order object. It can be useful for storing additional information about the order in a structured format.

  • selected_shipping_method string

    The shipping method that is currencly selected for this order, if any. If present, it is equal to one of the ids of shipping methods in the shipping_methods array. At order creation time, if there are multiple shipping methods, Stripe will automatically selected the first method.

  • shipping hash

    The shipping address for the order. Present if the order is for goods to be shipped.

    child attributes

    • address hash

      Customer shipping address.

      child attributes

      • city string

        City/Suburb/Town/Village

      • country string

        2-letter country code

      • line1 string

        Address line 1 (Street address/PO Box/Company name)

      • line2 string

        Address line 2 (Apartment/Suite/Unit/Building)

      • postal_code string

        Zip/Postal Code

      • state string

        State/Province/County

    • name string

      Customer name.

    • phone string

      Customer phone (including extension).

  • shipping_methods list

    A list of supported shipping methods for this order. The desired shipping method can be specified either by updating the order, or when paying it.

    child attributes

    • id string

    • amount integer

      A positive integer in the smallest currency unit (that is, 100 cents for $1.00, or 1 for ¥1, Japanese Yen being a 0-decimal currency) representing the total amount for the line item.

    • currency currency

      3-letter ISO code representing the currency of the line item.

    • description string

      Description of the line item, meant to be displayable to the user (e.g., "Express shipping").

  • status string

    Current order status. One of created, paid, canceled, fulfilled, or returned. More detail in the Relay API Overview.

  • updated timestamp 

{
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
#<Stripe::Order id=or_17WNfT2eZvKYlo2CrUDjSivR 0x00000a> JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
<Order order id=or_17WNfT2eZvKYlo2CrUDjSivR at 0x00000a> JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
Stripe\Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
com.stripe.model.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
{
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
&stripe.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}

Creating a new order

Creates a new order object.

Arguments

  • currency required

    3-letter ISO code representing the currency in which the order should be made. Stripe will convert the prices of the items associated with the order to this currency.

  • customer optional

    The ID of an existing customer to use for this order. If provided, the customer email and shipping address will be used to create the order. Subsequently, the customer will also be charged to pay the order. If email or shipping are also provided, they will override the values retrieved from the customer object.

  • email optional

    The email address of the customer placing the order.

  • items optional array of hashes

    List of items constituting the order.

    child arguments

    • amount optional

    • currency optional

    • description optional

    • parent optional

      The ID of the SKU being ordered.

    • quantity optional

      The quantity of this order item. When type is sku, this is the number of instances of the SKU to be ordered.

    • type optional

  • metadata optional

    A set of key/value pairs that you can attach to an order object. It can be useful for storing additional information about the order in a structured format.

  • shipping optional dictionaryhashdictionaryassociative arrayMapobjectmap

    Shipping address for the order. Required if any of the SKUs are for products that have shippable set to true.

    child arguments

    • address required

      child arguments

      • line1 required

      • city optional

      • country optional

      • line2 optional

      • postal_code optional

      • state optional

    • name required

    • phone optional

Returns

Returns an order object if the call succeeded. 

POST https://api.stripe.com/v1/orders
Stripe::Order.create
stripe.Order.create()
\Stripe\Order::create();
Order.create();
stripe.orders.create();
Order.New()
curl https://api.stripe.com/v1/orders \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d items[][type]=sku \
   -d items[][parent]=sku_7nxnrzcWC029db \
   -d currency=usd \
   -d shipping[name]="Jenny Rosen" \
   -d shipping[address][line1]="1234 Main Street" \
   -d shipping[address][city]=Anytown \
   -d shipping[address][country]=US \
   -d shipping[address][postal_code]=12356 \
   -d email="jenny@ros.en"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Order.create(
  :currency => 'usd',
  :items => [
    {
      :type => 'sku',
      :parent => 'sku_7nxnrzcWC029db'
    }
  ],
  :shipping => {
    :name => 'Jenny Rosen',
    :address => {
      :line1 => '1234 Main Street',
      :city => 'Anytown',
      :country => 'US',
      :postal_code => '123456'
    }
  },
  :email => 'jenny@ros.en',
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Order.create(
  currency='usd',
  items=[
    {
      type='sku',
      parent='sku_7nxnrzcWC029db'
    }
  ],
  shipping={
    name='Jenny Rosen',
    address={
      line1='1234 Main Street',
      city='Anytown',
      country='US',
      postal_code='123456'
    },
  },
  email='jenny@ros.en'
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Order::create(array(
  "items" => array(
    array(
      "type" => "sku",
      "parent" => "sku_7nxnrzcWC029db"
    )
  ),
  "currency" => "usd",
  "shipping" => array(
    "name" => "Jenny Rosen",
    "address" => array(
      "line1" => "1234 Main Street",
      "city" => "Anytown",
      "country" => "US",
      "postal_code" => "123456"
    )
  ),
  "email" => "jenny@ros.en"
);
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> orderParams = new HashMap<String, Object>();
orderParams.put("currency", usd);
orderParams.put("items", [{"type"=>"sku", "parent"=>"'sku_7nxnrzcWC029db'"}]);
Map<String, Object> shippingParams = new HashMap<String, Object>();
shippingParams.put("name", Jenny Rosen);
Map<String, Object> addressParams = new HashMap<String, Object>();
addressParams.put("line1", 1234 Main Street);
addressParams.put("city", Anytown);
addressParams.put("country", US);
addressParams.put("postal_code", 123456);
shippingParams.put("address", addressParams);
orderParams.put("shipping", shippingParams);
orderParams.put("email", jenny@ros.en);

Order.create(orderParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.orders.create({
  currency: 'usd',
  items: [
    {
      type: 'sku',
      parent: 'sku_7nxnrzcWC029db'
    }
  ],
  shipping: {
    name: 'Jenny Rosen',
    address: {
      line1: '1234 Main Street',
      city: 'Anytown',
      country: 'US',
      postal_code: '123456'
    }
  },
  email: 'jenny@ros.en'
}, function(err, order) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Order.New(&stripe.OrderParams{
  Currency: currency.USD,
  Items: []*stripe.OrderItemParams{
    &stripe.OrderItemParams{
      Type: "sku",
      Parent: "sku_7nxnrzcWC029db",
    },
  },
  Shipping: &stripe.ShippingParams{
    Name: "Jenny Rosen",
    Address: &stripe.AddressParams{
      Line1: "1234 Main Street",
      City: "Anytown",
      Country: "US",
      PostalCode: "123456",
    },
  },
  Email: "jenny@ros.en",
})
{
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
#<Stripe::Order id=or_17WNfT2eZvKYlo2CrUDjSivR 0x00000a> JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
<Order order id=or_17WNfT2eZvKYlo2CrUDjSivR at 0x00000a> JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
Stripe\Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
com.stripe.model.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
{
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
&stripe.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}

Errors

Types
sku_inactive The SKU that was specified is inactive.
product_inactive The product associated with the SKU that was specified is inactive.
out_of_inventory The SKU that was specified is out of stock.

Retrieve an order

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

Arguments

  • id required

    The identifier of the order to be retrieved.

Returns

Returns an order object if a valid identifier was provided.

curl https://api.stripe.com/v1/orders/or_17WNfT2eZvKYlo2CrUDjSivR \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Order.retrieve("or_17WNfT2eZvKYlo2CrUDjSivR")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Order.retrieve("or_17WNfT2eZvKYlo2CrUDjSivR")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Order::retrieve("or_17WNfT2eZvKYlo2CrUDjSivR");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Order.retrieve("or_17WNfT2eZvKYlo2CrUDjSivR");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.orders.retrieve(
  "or_17WNfT2eZvKYlo2CrUDjSivR",
  function(err, order) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

o, err := order.Get("or_17WNfT2eZvKYlo2CrUDjSivR", nil)
 
{
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
#<Stripe::Order id=or_17WNfT2eZvKYlo2CrUDjSivR 0x00000a> JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
<Order order id=or_17WNfT2eZvKYlo2CrUDjSivR at 0x00000a> JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
Stripe\Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
com.stripe.model.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
{
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
&stripe.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}

Update an order

Updates the specific order by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts only the metadata, and status as arguments.

Arguments

  • id required

  • coupon optional

    A coupon code that represents a discount to be applied to this order. Must be one-time duration and in same currency as the order.

  • metadata optional

    A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the order in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • selected_shipping_method optional

    The shipping method to select for fulfilling this order. If specified, must be one of the ids of a shipping method in the shipping_methods array. If specified, will overwrite the existing selected shipping method, updating items as necessary.

  • status optional

    Current order status. One of created, paid, canceled, fulfilled, or returned. More detail in the Relay API Overview.

Returns

Returns the order object if the update succeeded. 

POST https://api.stripe.com/v1/orders/{ORDER_ID}
order = Stripe::Order.retrieve({ORDER_ID})
order.metadata[{KEY}] = {VALUE}
order.save
order = stripe.Order.retrieve({ORDER_ID})
order.metadata[{KEY}] = {VALUE}
order.save()
$order = \Stripe\Order::retrieve({ORDER_ID});
$order->metadata[{KEY}] = {VALUE};
$order->save();
Order order = Order.retrieve({ORDER_ID});
Map metadata = new HashMap();
metdata.put({KEY}, {VALUE});
Map params = new HashMap();
params.put("metadata", metadata);
order.update(params);
stripe.orders.update({ORDER_ID}, {
  metadata: {{KEY}: {VALUE}}
})
order.Update({ORDER_ID}, &stripe.OrderUpdateParams{Meta: map[string]string{{KEY}: {VALUE}}})
 
curl https://api.stripe.com/v1/orders/or_17WNfT2eZvKYlo2CrUDjSivR \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

order = Stripe::Order.retrieve("or_17WNfT2eZvKYlo2CrUDjSivR")
order.metadata["key"] = "value"
order.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

order = stripe.Order.retrieve("or_17WNfT2eZvKYlo2CrUDjSivR")
order.metadata["key"] = "value"
order.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$order = \Stripe\Order::retrieve("or_17WNfT2eZvKYlo2CrUDjSivR");
$order->metadata["key"] = "value";
$order->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Order order = Order.retrieve("or_17WNfT2eZvKYlo2CrUDjSivR");
Map metadata = new HashMap();
metdata.put("key", "value");
Map params = new HashMap();
params.put("metadata", metadata);
refund.update(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.orders.update("or_17WNfT2eZvKYlo2CrUDjSivR", {
  metadata: {key: "value"}
)
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p, err := order.Update(
      "or_17WNfT2eZvKYlo2CrUDjSivR",
      &stripe.OrderParams{Meta: map[string]string{"key": "value"}}
)
 
{
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
#<Stripe::Order id=or_17WNfT2eZvKYlo2CrUDjSivR 0x00000a> JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
<Order order id=or_17WNfT2eZvKYlo2CrUDjSivR at 0x00000a> JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
Stripe\Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
com.stripe.model.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
{
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}
&stripe.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}

Pay an order

Pay an order by providing a source to create a payment.

Arguments

  • customer optional, either customer or source is required

    The ID of an existing customer that will be charged in this request.

  • source optional, either source or customer is required

    A payment source to be charged, such as a credit card. If you also pass a customer ID, the source must be the ID of a source belonging to the customer. Otherwise, if you do not pass a customer ID, the source you provide must either be a token, like the ones returned by Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's credit card details, with the options described below. Although not all information is required, the extra info helps prevent fraud.

    child attributes

    • exp_monthexp_monthexp_monthexp_monthexp_monthexp_monthexp_month required

      Two digit number representing the card's expiration month.

    • exp_yearexp_yearexp_yearexp_yearexp_yearexp_yearexp_year required

      Two or four digit number representing the card's expiration year.

    • numbernumbernumbernumbernumbernumbernumber required

      The card number, as a string without any separators.

    • objectobjectobjectobjectobjectobjectobject required

      The type of payment source. Should be "card".

    • cvccvccvccvccvccvccvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city optional

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • namenamenamenamenamenamename optional

      Cardholder's full name.

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

  • application_fee optional

    A fee in cents that will be applied to the order and transferred to the application owner's Stripe account. To use an application fee, the request must be made on behalf of another account, using the Stripe-Account header or OAuth key. For more information, see the application fees documentation.

  • email optional, but required if not previously specified

    The email address of the customer placing the order. If a customer is specified, that customer's email address will be used.

  • metadata optional

    A set of key/value pairs that you can attach to an order object. It can be useful for storing additional information about the order in a structured format.

Returns

Returns an order object along with its associated payment if the call succeeded. 

POST https://api.stripe.com/v1/orders/{ORDER_ID}/pay
Stripe::Order.pay
stripe.Order.pay()
\Stripe\Order::pay();
Order.pay();
stripe.orders.pay();
order.New()
 
curl https://api.stripe.com/v1/orders/or_17WNfT2eZvKYlo2CrUDjSivR/pay \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d source=tok_17YYPH2eZvKYlo2C8ZbpILPR

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

order = Stripe::Order.retrieve("or_17WNfT2eZvKYlo2CrUDjSivR")
order.pay(
  :source => "tok_17YYPH2eZvKYlo2C8ZbpILPR" # obtained with Stripe.js
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

order = stripe.Order.retrieve("or_17WNfT2eZvKYlo2CrUDjSivR")
order.pay(
  source="tok_17YYPH2eZvKYlo2C8ZbpILPR" # obtained with Stripe.js
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$order = \Stripe\Order::retrieve("or_17WNfT2eZvKYlo2CrUDjSivR");
$order->pay(array(
  "source" => "tok_17YYPH2eZvKYlo2C8ZbpILPR" // obtained with Stripe.js
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Order order = Order.retrieve("or_17WNfT2eZvKYlo2CrUDjSivR");
Map<String, Object> orderPayParams = new HashMap<String, Object>();
orderPayParams.put("source", "tok_17YYPH2eZvKYlo2C8ZbpILPR"); // obtained with Stripe.js)
order.pay(orderPayParams)
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.orders.pay("or_17WNfT2eZvKYlo2CrUDjSivR", {
  source: "tok_17YYPH2eZvKYlo2C8ZbpILPR" // obtained with Stripe.js
}, function(err, order) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

orderPayParams = &stripe.OrderPayParams{}
orderPayParams.SetSource("tok_17YYPH2eZvKYlo2C8ZbpILPR")
o, err := order.Pay(
  "or_17WNfT2eZvKYlo2CrUDjSivR",
  orderPayParams,
)
 
{
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "paid",
  "updated": 1453541211
}
#<Stripe::Order id=or_17WNfT2eZvKYlo2CrUDjSivR 0x00000a> JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "paid",
  "updated": 1453541211
}
<Order order id=or_17WNfT2eZvKYlo2CrUDjSivR at 0x00000a> JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "paid",
  "updated": 1453541211
}
Stripe\Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "paid",
  "updated": 1453541211
}
com.stripe.model.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "paid",
  "updated": 1453541211
}
{
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "paid",
  "updated": 1453541211
}
&stripe.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "paid",
  "updated": 1453541211
}

List all orders

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

Arguments

  • customer optional

    Only return orders for the given customer

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

  • ids optional

    Only return orders with the given IDs

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

  • status optional

    Only return orders that have the given status. One of created, paid, fulfilled, or refunded.

Returns

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

GET https://api.stripe.com/v1/orders
Stripe::Order.all
stripe.Order.all()
\Stripe\Order::all();
Order.all(Map<String, Object> options);
stripe.orders.list();
order.List()
 
curl https://api.stripe.com/v1/orders?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Order.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Order.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Order::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> orderParams = new HashMap<String, Object>();
orderParams.put("limit", 3);

Order.all(orderParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.orders.list(
  { limit: 3 },
  function(err, orders) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.OrderListParams{}
params.Filters.AddFilter("limit", "", "3")
i := order.List(params)
for i.Next() {
  o := i.Order()
}
 
{
  "object": "list",
  "url": "/v1/orders",
  "has_more": false,
  "data": [
    {
      "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
      "object": "order",
      "amount": 1500,
      "application": null,
      "application_fee": null,
      "charge": null,
      "created": 1453541211,
      "currency": "usd",
      "customer": null,
      "email": null,
      "items": [
        {
          "object": "order_item",
          "amount": 1500,
          "currency": "usd",
          "description": "2015 Limited Edition T-shirt",
          "parent": "sku_6zVDZYQHj7oq88",
          "quantity": 1,
          "type": "sku"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Taxes (included)",
          "parent": null,
          "quantity": null,
          "type": "tax"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping",
          "parent": "ship_free-shipping",
          "quantity": null,
          "type": "shipping"
        }
      ],
      "livemode": false,
      "metadata": {
      },
      "selected_shipping_method": "ship_free-shipping",
      "shipping": {
        "address": {
          "city": "Anytown",
          "country": "US",
          "line1": "1234 Main Street",
          "line2": null,
          "postal_code": "123456",
          "state": null
        },
        "name": "Jenny Rosen",
        "phone": null
      },
      "shipping_methods": [
        {
          "id": "ship_free-shipping",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping"
        }
      ],
      "status": "created",
      "updated": 1453541211
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/orders",
  "has_more": false,
  "data": [
    #<Stripe::Order id=or_17WNfT2eZvKYlo2CrUDjSivR 0x00000a> JSON: {
      "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
      "object": "order",
      "amount": 1500,
      "application": null,
      "application_fee": null,
      "charge": null,
      "created": 1453541211,
      "currency": "usd",
      "customer": null,
      "email": null,
      "items": [
        {
          "object": "order_item",
          "amount": 1500,
          "currency": "usd",
          "description": "2015 Limited Edition T-shirt",
          "parent": "sku_6zVDZYQHj7oq88",
          "quantity": 1,
          "type": "sku"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Taxes (included)",
          "parent": null,
          "quantity": null,
          "type": "tax"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping",
          "parent": "ship_free-shipping",
          "quantity": null,
          "type": "shipping"
        }
      ],
      "livemode": false,
      "metadata": {
      },
      "selected_shipping_method": "ship_free-shipping",
      "shipping": {
        "address": {
          "city": "Anytown",
          "country": "US",
          "line1": "1234 Main Street",
          "line2": null,
          "postal_code": "123456",
          "state": null
        },
        "name": "Jenny Rosen",
        "phone": null
      },
      "shipping_methods": [
        {
          "id": "ship_free-shipping",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping"
        }
      ],
      "status": "created",
      "updated": 1453541211
    },
    #<Stripe::Order[...] ...>,
    #<Stripe::Order[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/orders",
  has_more: false,
  data: [
    <Order order id=or_17WNfT2eZvKYlo2CrUDjSivR at 0x00000a> JSON: {
      "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
      "object": "order",
      "amount": 1500,
      "application": null,
      "application_fee": null,
      "charge": null,
      "created": 1453541211,
      "currency": "usd",
      "customer": null,
      "email": null,
      "items": [
        {
          "object": "order_item",
          "amount": 1500,
          "currency": "usd",
          "description": "2015 Limited Edition T-shirt",
          "parent": "sku_6zVDZYQHj7oq88",
          "quantity": 1,
          "type": "sku"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Taxes (included)",
          "parent": null,
          "quantity": null,
          "type": "tax"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping",
          "parent": "ship_free-shipping",
          "quantity": null,
          "type": "shipping"
        }
      ],
      "livemode": false,
      "metadata": {
      },
      "selected_shipping_method": "ship_free-shipping",
      "shipping": {
        "address": {
          "city": "Anytown",
          "country": "US",
          "line1": "1234 Main Street",
          "line2": null,
          "postal_code": "123456",
          "state": null
        },
        "name": "Jenny Rosen",
        "phone": null
      },
      "shipping_methods": [
        {
          "id": "ship_free-shipping",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping"
        }
      ],
      "status": "created",
      "updated": 1453541211
    },
    <stripe.Order[...] ...>,
    <stripe.Order[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/orders",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Order JSON: {
      "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
      "object": "order",
      "amount": 1500,
      "application": null,
      "application_fee": null,
      "charge": null,
      "created": 1453541211,
      "currency": "usd",
      "customer": null,
      "email": null,
      "items": [
        {
          "object": "order_item",
          "amount": 1500,
          "currency": "usd",
          "description": "2015 Limited Edition T-shirt",
          "parent": "sku_6zVDZYQHj7oq88",
          "quantity": 1,
          "type": "sku"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Taxes (included)",
          "parent": null,
          "quantity": null,
          "type": "tax"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping",
          "parent": "ship_free-shipping",
          "quantity": null,
          "type": "shipping"
        }
      ],
      "livemode": false,
      "metadata": {
      },
      "selected_shipping_method": "ship_free-shipping",
      "shipping": {
        "address": {
          "city": "Anytown",
          "country": "US",
          "line1": "1234 Main Street",
          "line2": null,
          "postal_code": "123456",
          "state": null
        },
        "name": "Jenny Rosen",
        "phone": null
      },
      "shipping_methods": [
        {
          "id": "ship_free-shipping",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping"
        }
      ],
      "status": "created",
      "updated": 1453541211
    }
    [1] => <Stripe\Order[...] ...>
    [2] => <Stripe\Order[...] ...>
  ]
}
#<com.stripe.model.OrderCollection id=#> JSON: {
  "data": [
    com.stripe.model.Order JSON: {
      "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
      "object": "order",
      "amount": 1500,
      "application": null,
      "application_fee": null,
      "charge": null,
      "created": 1453541211,
      "currency": "usd",
      "customer": null,
      "email": null,
      "items": [
        {
          "object": "order_item",
          "amount": 1500,
          "currency": "usd",
          "description": "2015 Limited Edition T-shirt",
          "parent": "sku_6zVDZYQHj7oq88",
          "quantity": 1,
          "type": "sku"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Taxes (included)",
          "parent": null,
          "quantity": null,
          "type": "tax"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping",
          "parent": "ship_free-shipping",
          "quantity": null,
          "type": "shipping"
        }
      ],
      "livemode": false,
      "metadata": {
      },
      "selected_shipping_method": "ship_free-shipping",
      "shipping": {
        "address": {
          "city": "Anytown",
          "country": "US",
          "line1": "1234 Main Street",
          "line2": null,
          "postal_code": "123456",
          "state": null
        },
        "name": "Jenny Rosen",
        "phone": null
      },
      "shipping_methods": [
        {
          "id": "ship_free-shipping",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping"
        }
      ],
      "status": "created",
      "updated": 1453541211
    },
    #<com.stripe.model.Order[...] ...>,
    #<com.stripe.model.Order[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/orders",
  "has_more": false,
  "data": [
    {
      "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
      "object": "order",
      "amount": 1500,
      "application": null,
      "application_fee": null,
      "charge": null,
      "created": 1453541211,
      "currency": "usd",
      "customer": null,
      "email": null,
      "items": [
        {
          "object": "order_item",
          "amount": 1500,
          "currency": "usd",
          "description": "2015 Limited Edition T-shirt",
          "parent": "sku_6zVDZYQHj7oq88",
          "quantity": 1,
          "type": "sku"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Taxes (included)",
          "parent": null,
          "quantity": null,
          "type": "tax"
        },
        {
          "object": "order_item",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping",
          "parent": "ship_free-shipping",
          "quantity": null,
          "type": "shipping"
        }
      ],
      "livemode": false,
      "metadata": {
      },
      "selected_shipping_method": "ship_free-shipping",
      "shipping": {
        "address": {
          "city": "Anytown",
          "country": "US",
          "line1": "1234 Main Street",
          "line2": null,
          "postal_code": "123456",
          "state": null
        },
        "name": "Jenny Rosen",
        "phone": null
      },
      "shipping_methods": [
        {
          "id": "ship_free-shipping",
          "amount": 0,
          "currency": "usd",
          "description": "Free shipping"
        }
      ],
      "status": "created",
      "updated": 1453541211
    },
    {...},
    {...}
  ]
}
&stripe.Order JSON: {
  "id": "or_17WNfT2eZvKYlo2CrUDjSivR",
  "object": "order",
  "amount": 1500,
  "application": null,
  "application_fee": null,
  "charge": null,
  "created": 1453541211,
  "currency": "usd",
  "customer": null,
  "email": null,
  "items": [
    {
      "object": "order_item",
      "amount": 1500,
      "currency": "usd",
      "description": "2015 Limited Edition T-shirt",
      "parent": "sku_6zVDZYQHj7oq88",
      "quantity": 1,
      "type": "sku"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Taxes (included)",
      "parent": null,
      "quantity": null,
      "type": "tax"
    },
    {
      "object": "order_item",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping",
      "parent": "ship_free-shipping",
      "quantity": null,
      "type": "shipping"
    }
  ],
  "livemode": false,
  "metadata": {
  },
  "selected_shipping_method": "ship_free-shipping",
  "shipping": {
    "address": {
      "city": "Anytown",
      "country": "US",
      "line1": "1234 Main Street",
      "line2": null,
      "postal_code": "123456",
      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null
  },
  "shipping_methods": [
    {
      "id": "ship_free-shipping",
      "amount": 0,
      "currency": "usd",
      "description": "Free shipping"
    }
  ],
  "status": "created",
  "updated": 1453541211
}

Order Items

A representation of the constituent items of any given order. Can be used to represent SKUs, shipping costs, or taxes owed on the order.

The order_item object

Attributes

  • object string , value is "order_item"

  • amount integer

    A positive integer in the smallest currency unit (that is, 100 cents for $1.00, or 1 for ¥1, Japanese Yen being a 0-decimal currency) representing the total amount for the line item.

  • currency currency

    3-letter ISO code representing the currency of the line item.

  • description string

    Description of the line item, meant to be displayable to the user (e.g., "Express shipping").

  • parent string

    The ID of the associated object for this line item. Expandable if not null (e.g., expandable to a SKU).

  • quantity positive integer

    A positive integer representing the number of instances of parent that are included in this order item. Applicable/present only if type is sku.

  • type string

    The type of line item. One of sku, tax, shipping, or discount. 

{
  "object": "order_item",
  "amount": 0,
  "currency": "usd",
  "description": "Free shipping",
  "parent": "ship_free-shipping",
  "quantity": null,
  "type": "shipping"
}
#<Stripe::OrderItem 0x00000a> JSON: {
  "object": "order_item",
  "amount": 0,
  "currency": "usd",
  "description": "Free shipping",
  "parent": "ship_free-shipping",
  "quantity": null,
  "type": "shipping"
}
<OrderItem order_item at 0x00000a> JSON: {
  "object": "order_item",
  "amount": 0,
  "currency": "usd",
  "description": "Free shipping",
  "parent": "ship_free-shipping",
  "quantity": null,
  "type": "shipping"
}
Stripe\OrderItem JSON: {
  "object": "order_item",
  "amount": 0,
  "currency": "usd",
  "description": "Free shipping",
  "parent": "ship_free-shipping",
  "quantity": null,
  "type": "shipping"
}
com.stripe.model.OrderItem JSON: {
  "object": "order_item",
  "amount": 0,
  "currency": "usd",
  "description": "Free shipping",
  "parent": "ship_free-shipping",
  "quantity": null,
  "type": "shipping"
}
{
  "object": "order_item",
  "amount": 0,
  "currency": "usd",
  "description": "Free shipping",
  "parent": "ship_free-shipping",
  "quantity": null,
  "type": "shipping"
}
&stripe.OrderItem JSON: {
  "object": "order_item",
  "amount": 0,
  "currency": "usd",
  "description": "Free shipping",
  "parent": "ship_free-shipping",
  "quantity": null,
  "type": "shipping"
}

Products

Store representations of products you sell in product objects, used in conjunction with SKUs. Products may be physical goods, to be shipped, or digital.

The product object

Attributes

  • id string

  • object string , value is "product"

  • active boolean

    Whether or not the product is currently available for purchase.

  • attributes array containing strings

    A list of up to 5 attributes that each SKU can provide values for (e.g. ["color", "size"]).

  • caption string

    A short one-line description of the product, meant to be displayable to the customer.

  • created timestamp

  • description string

    The product’s description, meant to be displayable to the customer.

  • images array containing urls

    A list of up to 8 URLs of images for this product, meant to be displayable to the customer.

  • livemode boolean

  • metadata #

    A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format.

  • name string

    The product’s name, meant to be displayable to the customer.

  • package_dimensions hash

    The dimensions of this product for shipping purposes. A SKU associated with this product can override this value by having its own package_dimensions

    child attributes

    • height decimal

      Height, in inches

    • length decimal

      Length, in inches

    • weight decimal

      Weight, in ounces

    • width decimal

      Width, in inches

  • shippable boolean

    Whether this product is a shipped good.

  • skus list

    A sublist of active SKUs associated with this product.

    child attributes

    • object string , value is "list"

    • data array, contains: sku object

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • updated timestamp

  • url string

    A URL of a publicly-accessible webpage for this product. 

{
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
#<Stripe::Product id=prod_7hBYqlzyTVzjQd 0x00000a> JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
<Product product id=prod_7hBYqlzyTVzjQd at 0x00000a> JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
Stripe\Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
com.stripe.model.Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
{
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
&stripe.Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}

Create a product

Creates a new product object.

Arguments

  • id optional

    The identifier for the product. Must be unique. If not provided, an identifier will be randomly generated.

  • name required

    The product’s name, meant to be displayable to the customer.

  • active optional

    Whether or not the product is currently available for purchase. Defaults to true.

  • attributes optional

    A list of up to 5 alphanumeric attributes that each SKU can provide values for (e.g. ["color", "size"]).

  • caption optional

    A short one-line description of the product, meant to be displayable to the customer.

  • description optional

    The product’s description, meant to be displayable to the customer.

  • images optional

    A list of up to 8 URLs of images for this product, meant to be displayable to the customer.

  • metadata optional

    A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format.

  • package_dimensions optional dictionaryhashdictionaryassociative arrayMapobjectmap

    The dimensions of this product for shipping purposes. A SKU associated with this product can override this value by having its own package_dimensions

    child arguments

    • height required

      Height, in inches. Maximum precision is 2 decimal places.

    • length required

      Length, in inches. Maximum precision is 2 decimal places.

    • weight required

      Weight, in ounces. Maximum precision is 2 decimal places.

    • width required

      Width, in inches. Maximum precision is 2 decimal places.

  • shippable optional

    Whether this product is shipped (i.e. physical goods). Defaults to true.

  • url optional

    A URL of a publicly-accessible webpage for this product.

Returns

Returns a product object if the call succeeded. 

POST https://api.stripe.com/v1/products
Stripe::Product.create
stripe.Product.create()
\Stripe\Product::create();
Product.create();
stripe.products.create();
Product.New()
 
curl https://api.stripe.com/v1/products \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name=T-shirt \
   -d description="Comfortable gray cotton t-shirts" \
   -d attributes[]=size \
   -d attributes[]=gender

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Product.create(
  :name => 'T-shirt',
  :description => 'Comfortable gray cotton t-shirts',
  :attributes => ['size', 'gender']
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Product.create(
  name='T-shirt',
  description='Comfortable gray cotton t-shirts',
  attributes=['size', 'gender']
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Product::create(array(
  "name" => 'T-shirt',
  "description" => "Comfortable gray cotton t-shirts",
  "attributes" => ["size", "gender"]
);
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> productParams = new HashMap<String, Object>();
productParams.put("name", T-shirt);
productParams.put("description", "Comfortable gray cotton t-shirts");
productParams.put("attributes", ["size", "gender"]);

Product.create(productParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.products.create({
  name: 'T-shirt',
  description: 'Comfortable gray cotton t-shirts',
  attributes: ['size', 'gender']
}, function(err, product) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Product.New(&stripe.ProductParams{
  Name: "T-shirt",
  Description: "Comfortable gray cotton t-shirts",
  Attributes: []string{"size", "gender"},
})
 
{
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
#<Stripe::Product id=prod_7hBYqlzyTVzjQd 0x00000a> JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
<Product product id=prod_7hBYqlzyTVzjQd at 0x00000a> JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
Stripe\Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
com.stripe.model.Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
{
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
&stripe.Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}

Retrieve a product

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

Arguments

  • id required

    The identifier of the product to be retrieved.

Returns

Returns a product object if a valid identifier was provided.

curl https://api.stripe.com/v1/products/prod_7hBYqlzyTVzjQd \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Product.retrieve("prod_7hBYqlzyTVzjQd")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Product.retrieve("prod_7hBYqlzyTVzjQd")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Product::retrieve("prod_7hBYqlzyTVzjQd");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Product.retrieve("prod_7hBYqlzyTVzjQd");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.products.retrieve(
  "prod_7hBYqlzyTVzjQd",
  function(err, product) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p, err := product.Get("prod_7hBYqlzyTVzjQd", nil)
 
{
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
#<Stripe::Product id=prod_7hBYqlzyTVzjQd 0x00000a> JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
<Product product id=prod_7hBYqlzyTVzjQd at 0x00000a> JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
Stripe\Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
com.stripe.model.Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
{
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
&stripe.Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}

Update a product

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

Note that a product's attributes are not editable. Instead, you would need to deactivate the existing product and create a new one with the new attribute values.

Arguments

  • active optional

    Whether or not the product is available for purchase. Setting this to false also deactivates any active, related SKUs. Setting this to true does not automatically activate any deactivated, related SKUs.

  • caption optional

    A short one-line description of the product, meant to be displayable to the customer.

  • description optional

    The product’s description, meant to be displayable to the customer.

  • images optional

    A list of up to 8 URLs of images for this product, meant to be displayable to the customer. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • metadata optional

    A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • name optional

    The product’s name, meant to be displayable to the customer.

  • package_dimensions optional dictionaryhashdictionaryassociative arrayMapobjectmap

    The dimensions of this product for shipping purposes. A SKU associated with this product can override this value by having its own package_dimensions

    child arguments

    • height required

      Height, in inches. Maximum precision is 2 decimal places.

    • length required

      Length, in inches. Maximum precision is 2 decimal places.

    • weight required

      Weight, in ounces. Maximum precision is 2 decimal places.

    • width required

      Width, in inches. Maximum precision is 2 decimal places.

  • shippable optional

    Whether this product is shipped (i.e. physical goods). Defaults to true.

  • url optional

    A URL of a publicly-accessible webpage for this product.

Returns

Returns the product object if the update succeeded. 

POST https://api.stripe.com/v1/products/{PRODUCT_ID}
product = Stripe::Product.retrieve({PRODUCT_ID})
product.metadata[{KEY}] = {VALUE}
product.save
product = stripe.Product.retrieve({PRODUCT_ID})
product.metadata[{KEY}] = {VALUE}
product.save()
$product = \Stripe\Product::retrieve({PRODUCT_ID});
$product->metadata[{KEY}] = {VALUE};
$product->save();
Product product = Product.retrieve({PRODUCT_ID});
Map metadata = new HashMap();
metdata.put({KEY}, {VALUE});
Map params = new HashMap();
params.put("metadata", metadata);
product.update(params);
stripe.products.update({PRODUCT_ID}, {
  metadata: {{KEY}: {VALUE}}
})
product.Update({PRODUCT_ID}, &stripe.ProductParams{Meta: map[string]string{{KEY}: {VALUE}}})
 
curl https://api.stripe.com/v1/products/pr_17RnBW2eZvKYlo2Csnbv2kUq \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

product = Stripe::Product.retrieve("pr_17RnBW2eZvKYlo2Csnbv2kUq")
product.metadata["key"] = "value"
product.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

product = stripe.Product.retrieve("pr_17RnBW2eZvKYlo2Csnbv2kUq")
product.metadata["key"] = "value"
product.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$product = \Stripe\Product::retrieve("pr_17RnBW2eZvKYlo2Csnbv2kUq");
$product->metadata["key"] = "value";
$product->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Product product = Product.retrieve("pr_17RnBW2eZvKYlo2Csnbv2kUq");
Map metadata = new HashMap();
metdata.put("key", "value");
Map params = new HashMap();
params.put("metadata", metadata);
refund.update(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.products.update("pr_17RnBW2eZvKYlo2Csnbv2kUq", {
  metadata: {key: "value"}
)
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p, err := product.Update(
      "pr_17RnBW2eZvKYlo2Csnbv2kUq",
      &stripe.ProductParams{Meta: map[string]string{"key": "value"}}
)
 
{
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
#<Stripe::Product id=prod_7hBYqlzyTVzjQd 0x00000a> JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
<Product product id=prod_7hBYqlzyTVzjQd at 0x00000a> JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
Stripe\Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
com.stripe.model.Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
{
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}
&stripe.Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}

List all products

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

Arguments

  • active optional

    Only return products that are active or inactive (e.g. pass false to list all inactive products).

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

  • ids optional

    Only return products with the given IDs.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • shippable optional

    Only return products that can be shipped (i.e., physical, not digital products).

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

  • url optional

    Only return products with the given url

Returns

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

GET https://api.stripe.com/v1/products
Stripe::Product.all
stripe.Product.all()
\Stripe\Product::all();
Product.all(Map<String, Object> options);
stripe.products.list();
product.List()
 
curl https://api.stripe.com/v1/products?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Product.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Product.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Product::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> productParams = new HashMap<String, Object>();
productParams.put("limit", 3);

Product.all(productParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.products.list(
  { limit: 3 },
  function(err, products) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ProductListParams{}
params.Filters.AddFilter("limit", "", "3")
i := product.List(params)
for i.Next() {
  p := i.Product()
}
 
{
  "object": "list",
  "url": "/v1/products",
  "has_more": false,
  "data": [
    {
      "id": "prod_7hBYqlzyTVzjQd",
      "object": "product",
      "active": true,
      "attributes": [
        "size",
        "gender"
      ],
      "caption": null,
      "created": 1452447658,
      "description": "Comfortable gray cotton t-shirts",
      "images": [
    
      ],
      "livemode": false,
      "metadata": {
      },
      "name": "T-shirt",
      "package_dimensions": null,
      "shippable": true,
      "skus": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
      },
      "updated": 1452447658,
      "url": null
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/products",
  "has_more": false,
  "data": [
    #<Stripe::Product id=prod_7hBYqlzyTVzjQd 0x00000a> JSON: {
      "id": "prod_7hBYqlzyTVzjQd",
      "object": "product",
      "active": true,
      "attributes": [
        "size",
        "gender"
      ],
      "caption": null,
      "created": 1452447658,
      "description": "Comfortable gray cotton t-shirts",
      "images": [
    
      ],
      "livemode": false,
      "metadata": {
      },
      "name": "T-shirt",
      "package_dimensions": null,
      "shippable": true,
      "skus": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
      },
      "updated": 1452447658,
      "url": null
    },
    #<Stripe::Product[...] ...>,
    #<Stripe::Product[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/products",
  has_more: false,
  data: [
    <Product product id=prod_7hBYqlzyTVzjQd at 0x00000a> JSON: {
      "id": "prod_7hBYqlzyTVzjQd",
      "object": "product",
      "active": true,
      "attributes": [
        "size",
        "gender"
      ],
      "caption": null,
      "created": 1452447658,
      "description": "Comfortable gray cotton t-shirts",
      "images": [
    
      ],
      "livemode": false,
      "metadata": {
      },
      "name": "T-shirt",
      "package_dimensions": null,
      "shippable": true,
      "skus": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
      },
      "updated": 1452447658,
      "url": null
    },
    <stripe.Product[...] ...>,
    <stripe.Product[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/products",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Product JSON: {
      "id": "prod_7hBYqlzyTVzjQd",
      "object": "product",
      "active": true,
      "attributes": [
        "size",
        "gender"
      ],
      "caption": null,
      "created": 1452447658,
      "description": "Comfortable gray cotton t-shirts",
      "images": [
    
      ],
      "livemode": false,
      "metadata": {
      },
      "name": "T-shirt",
      "package_dimensions": null,
      "shippable": true,
      "skus": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
      },
      "updated": 1452447658,
      "url": null
    }
    [1] => <Stripe\Product[...] ...>
    [2] => <Stripe\Product[...] ...>
  ]
}
#<com.stripe.model.ProductCollection id=#> JSON: {
  "data": [
    com.stripe.model.Product JSON: {
      "id": "prod_7hBYqlzyTVzjQd",
      "object": "product",
      "active": true,
      "attributes": [
        "size",
        "gender"
      ],
      "caption": null,
      "created": 1452447658,
      "description": "Comfortable gray cotton t-shirts",
      "images": [
    
      ],
      "livemode": false,
      "metadata": {
      },
      "name": "T-shirt",
      "package_dimensions": null,
      "shippable": true,
      "skus": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
      },
      "updated": 1452447658,
      "url": null
    },
    #<com.stripe.model.Product[...] ...>,
    #<com.stripe.model.Product[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/products",
  "has_more": false,
  "data": [
    {
      "id": "prod_7hBYqlzyTVzjQd",
      "object": "product",
      "active": true,
      "attributes": [
        "size",
        "gender"
      ],
      "caption": null,
      "created": 1452447658,
      "description": "Comfortable gray cotton t-shirts",
      "images": [
    
      ],
      "livemode": false,
      "metadata": {
      },
      "name": "T-shirt",
      "package_dimensions": null,
      "shippable": true,
      "skus": {
        "object": "list",
        "data": [
    
        ],
        "has_more": false,
        "total_count": 0,
        "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
      },
      "updated": 1452447658,
      "url": null
    },
    {...},
    {...}
  ]
}
&stripe.Product JSON: {
  "id": "prod_7hBYqlzyTVzjQd",
  "object": "product",
  "active": true,
  "attributes": [
    "size",
    "gender"
  ],
  "caption": null,
  "created": 1452447658,
  "description": "Comfortable gray cotton t-shirts",
  "images": [

  ],
  "livemode": false,
  "metadata": {
  },
  "name": "T-shirt",
  "package_dimensions": null,
  "shippable": true,
  "skus": {
    "object": "list",
    "data": [

    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/skus?product=prod_7hBYqlzyTVzjQd\u0026active=true"
  },
  "updated": 1452447658,
  "url": null
}

Delete a product

Delete a product. Deleting a product is only possible if it has no SKUs associated with it.

Arguments

  • id required

    The ID of the product to delete

Returns

Returns an object with a deleted parameter on success. Otherwise, this call returnsraisesraisesthrowsthrowsthrowsreturns an error 

DELETE https://api.stripe.com/v1/products/{PRODUCT_ID}
product = Stripe::Product.retrieve({PRODUCT_ID})
product.delete
product = stripe.Product.retrieve({PRODUCT_ID})
product.delete()
$product = \Stripe\Product::retrieve({PRODUCT_ID});
$product->delete();
Product product = Product.retrieve({PRODUCT_ID});
product.delete();
stripe.products.del({PRODUCT_ID});
product.Del({PRODUCT_ID})
 
curl https://api.stripe.com/v1/products/%22prod_7hBYqlzyTVzjQd%22 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

product = Stripe::Product.retrieve("prod_7hBYqlzyTVzjQd")
product.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

product = stripe.Product.retrieve("prod_7hBYqlzyTVzjQd")
product.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$product = \Stripe\Product::retrieve("prod_7hBYqlzyTVzjQd");
$product->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Product product = Product.retrieve("prod_7hBYqlzyTVzjQd");
product.delete(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.products.del("prod_7hBYqlzyTVzjQd",
  function(err, confirmation) {
    // asynchronously called
  },
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := product.Delete("prod_7hBYqlzyTVzjQd")
 
{
  "deleted": true,
  "id": "pr_17RnBW2eZvKYlo2Csnbv2kUq"
}
#<Stripe::Object id=pr_17RnBW2eZvKYlo2Csnbv2kUq 0x00000a> JSON: {
  "deleted": true,
  "id": "pr_17RnBW2eZvKYlo2Csnbv2kUq"
}
<Object object id=pr_17RnBW2eZvKYlo2Csnbv2kUq at 0x00000a> JSON: {
  "deleted": true,
  "id": "pr_17RnBW2eZvKYlo2Csnbv2kUq"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "pr_17RnBW2eZvKYlo2Csnbv2kUq"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "pr_17RnBW2eZvKYlo2Csnbv2kUq"
}
{
  "deleted": true,
  "id": "pr_17RnBW2eZvKYlo2Csnbv2kUq"
}
&stripe.Object JSON: {
  "deleted": true,
  "id": "pr_17RnBW2eZvKYlo2Csnbv2kUq"
}

SKUs

Stores representations of stock keeping units. SKUs describe specific product variations, taking into account any combination of: attributes, currency, and cost. For example, a product may be a t- shirt, whereas a specific SKU represents the size: large, color: red version of that shirt.

Can also be used to manage inventory.

The sku object

Attributes

  • id string

  • object string , value is "sku"

  • active boolean

    Whether or not the SKU is available for purchase.

  • attributes hash

    A dictionary of attributes and values for the attributes defined by the product. If, for example, a product’s attributes are ["size", "gender"], a valid SKU has the following dictionary of attributes: {"size": "Medium", "gender": "Unisex"}.

  • created timestamp

  • currency currency

    3-letter ISO code for currency.

  • image string

    The URL of an image for this SKU, meant to be displayable to the customer.

  • inventory hash

    Description of the SKU’s inventory.

    child attributes

    • quantity positive integer or zero

      The count of inventory available. Will be present if and only if type is finite.

    • type string

      Inventory type. Possible values are finite, bucket (not quantified), and infinite.

    • value string

      An indicator of the inventory available. Possible values are in_stock, limited, and out_of_stock. Will be present if and only if type is bucket.

  • livemode boolean

  • metadata #

    A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format.

  • package_dimensions hash

    The dimensions of this SKU for shipping purposes.

    child attributes

    • height decimal

      Height, in inches

    • length decimal

      Length, in inches

    • weight decimal

      Weight, in ounces

    • width decimal

      Width, in inches

  • price positive integer

    The cost of the item as a positive integer in the smallest currency unit (that is, 100 cents to charge $1.00, or 1 to charge ¥1, Japanese Yen being a 0-decimal currency).

  • product string

    The ID of the product this SKU is associated with. The product must be currently active.

  • updated timestamp 

{
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
#<Stripe::SKU id=sku_7nxnrzcWC029db 0x00000a> JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
<SKU sku id=sku_7nxnrzcWC029db at 0x00000a> JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
Stripe\SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
com.stripe.model.SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
{
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
&stripe.SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}

Create a SKU

Creates a new SKU associated with a product.

Arguments

  • id optional

    The identifier for the SKU. Must be unique. If not provided, an identifier will be randomly generated.

  • currency required

    3-letter ISO code for currency.

  • inventory required

    Description of the SKU’s inventory.

    child arguments

    • type required

      Inventory type. Possible values are finite, bucket (not quantified), and infinite.

    • quantity optional

      The count of inventory available. Required if type is finite.

    • value optional

      An indicator of the inventory available. Possible values are in_stock, limited, and out_of_stock. Will be present if and only if type is bucket.

  • price required

    The cost of the item as a positive integer in the smallest currency unit (that is, 100 cents to charge $1.00, or 1 to charge ¥1, Japanese Yen being a 0-decimal currency).

  • product required

    The ID of the product this SKU is associated with.

  • active optional

    Whether or not the SKU is available for purchase. Default to true.

  • attributes optional

    A dictionary of attributes and values for the attributes defined by the product. If, for example, a product’s attributes are ["size", "gender"], a valid SKU has the following dictionary of attributes: {"size": "Medium", "gender": "Unisex"}.

  • image optional

    The URL of an image for this SKU, meant to be displayable to the customer.

  • metadata optional

    A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format.

  • package_dimensions optional dictionaryhashdictionaryassociative arrayMapobjectmap

    The dimensions of this SKU for shipping purposes.

    child arguments

    • height required

      Height, in inches. Maximum precision is 2 decimal places.

    • length required

      Length, in inches. Maximum precision is 2 decimal places.

    • weight required

      Weight, in ounces. Maximum precision is 2 decimal places.

    • width required

      Width, in inches. Maximum precision is 2 decimal places.

Returns

Returns a SKU object if the call succeeded. 

POST https://api.stripe.com/v1/skus
Stripe::SKU.create
stripe.SKU.create()
\Stripe\SKU::create();
SKU.create();
stripe.skus.create();
SKU.New()
 
curl https://api.stripe.com/v1/skus \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d attributes[size]=Medium \
   -d attributes[gender]=Unisex \
   -d price=1500 \
   -d currency=usd \
   -d inventory[type]=finite \
   -d inventory[quantity]=500 \
   -d product=pr_17RnBW2eZvKYlo2Csnbv2kUq

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::SKU.create(
  :product => 'pr_17RnBW2eZvKYlo2Csnbv2kUq',
  :attributes => {
    'size' => 'Medium',
    'gender' => 'Unisex'
  },
  :price => 1500,
  :currency => 'usd',
  :inventory => {
    'type' => 'finite',
    'quantity' => 500
  }
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.SKU.create(
  product='pr_17RnBW2eZvKYlo2Csnbv2kUq',
  attributes={'size': 'Medium', 'gender': 'Unisex'},
  price=1500,
  currency='usd',
  inventory={'type': 'finite', 'quantity': 500}
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\SKU::create(array(
  "product" => "pr_17RnBW2eZvKYlo2Csnbv2kUq",
  "attributes" => array(
    "size" => "Medium",
    "gender" => "Unisex"
  ),
  "price" => 1500,
  "currency" => "usd",
  "inventory" => array(
    "type" => "finite",
    "quantity" => 500
  )
);
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> skuParams = new HashMap<String, Object>();
skuParams.put("product", "pr_17RnBW2eZvKYlo2Csnbv2kUq");
skuParams.put("price", 1500);
skuParams.put("currency", "usd");
Map<String, Object> attributesParams = new HashMap<String, Object>();
attributesParams.put("size", "Medium");
attributesParams.put("gender", "Unisex");
skuParams.put("attributes", attributesParams);
Map<String, Object> inventoryParams = new HashMap<String, Object>();
inventoryParams.put("type", "finite");
inventoryParams.put("quantity", 500);
skuParams.put("inventory", inventoryParams);

Sku.create(skuParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.skus.create({
  product: 'pr_17RnBW2eZvKYlo2Csnbv2kUq',
  attributes: {size: 'Medium', gender: 'Unisex'},
  price: 1500,
  currency: 'usd',
  inventory: {type: 'finite', quantity: 500}
}, function(err, sku) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

SKU.New(&stripe.SKUParams{
  Product: "pr_17RnBW2eZvKYlo2Csnbv2kUq",
  Attributes: [string]string{
    "size" => "Medium",
    "gender" => "Unisex"
  },
  Price: 1500,
  Currency: "usd",
  Inventory: [string]string{
    "type" => "finite",
    "quantity" => "500"
  },
})
 
{
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
#<Stripe::SKU id=sku_7nxnrzcWC029db 0x00000a> JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
<SKU sku id=sku_7nxnrzcWC029db at 0x00000a> JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
Stripe\SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
com.stripe.model.SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
{
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
&stripe.SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}

Retrieve a SKU

Retrieves the details of an existing SKU. Supply the unique SKU identifier from either a SKU creation request or from the product, and Stripe will return the corresponding SKU information.

Arguments

  • id required

    The identifier of the SKU to be retrieved.

Returns

Returns a SKU object if a valid identifier was provided.

curl https://api.stripe.com/v1/skus/sku_7nxnrzcWC029db \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Sku.retrieve("sku_7nxnrzcWC029db")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Sku.retrieve("sku_7nxnrzcWC029db")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Sku::retrieve("sku_7nxnrzcWC029db");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Sku.retrieve("sku_7nxnrzcWC029db");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.skus.retrieve(
  "sku_7nxnrzcWC029db",
  function(err, sku) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

s, err := sku.Get("sku_7nxnrzcWC029db", nil)
 
{
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
#<Stripe::SKU id=sku_7nxnrzcWC029db 0x00000a> JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
<SKU sku id=sku_7nxnrzcWC029db at 0x00000a> JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
Stripe\SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
com.stripe.model.SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
{
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
&stripe.SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}

Update a SKU

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

Note that a SKU's attributes are not editable. Instead, you would need to deactivate the existing SKU and create a new one with the new attribute values.

Arguments

  • active optional

    Whether or not this SKU is available for purchase.

  • currency optional

    3-letter ISO code for currency.

  • image optional

    The URL of an image for this SKU, meant to be displayable to the customer. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • inventory optional

    Description of the SKU’s inventory.

  • metadata optional

    A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • package_dimensions optional dictionaryhashdictionaryassociative arrayMapobjectmap

    The dimensions of this SKU for shipping purposes.

    child arguments

    • height required

      Height, in inches. Maximum precision is 2 decimal places.

    • length required

      Length, in inches. Maximum precision is 2 decimal places.

    • weight required

      Weight, in ounces. Maximum precision is 2 decimal places.

    • width required

      Width, in inches. Maximum precision is 2 decimal places.

  • price optional

    The cost of the item as a positive integer in the smallest currency unit (that is, 100 cents to charge $1.00, or 1 to charge ¥1, Japanese Yen being a 0-decimal currency).

  • product optional

    The ID of the product that this SKU should belong to. The product must exist and have the same set of attribute names as the SKU’s current product.

Returns

Returns a SKU object if the call succeeded. 

POST https://api.stripe.com/v1/skus/{SKU_ID}
sku = Stripe::SKU.retrieve({SKU_ID})
sku.metadata[{KEY}] = {VALUE}
sku.save
sku = stripe.SKU.retrieve({SKU_ID})
sku.metadata[{KEY}] = {VALUE}
sku.save()
$sku = \Stripe\SKU::retrieve({SKU_ID});
$sku->metadata[{KEY}] = {VALUE};
$sku->save();
SKU sku = SKU.retrieve({SKU_ID});
Map metadata = new HashMap();
metdata.put({KEY}, {VALUE});
Map params = new HashMap();
params.put("metadata", metadata);
sku.update(params);
stripe.skus.update({SKU_ID}, {
  metadata: {{KEY}: {VALUE}}
})
sku.Update({SKU_ID}, &stripe.SKUParams{Meta: map[string]string{{KEY}: {VALUE}}})
 
curl https://api.stripe.com/v1/skus/sk_17YLrW2eZvKYlo2Czz70fPGC \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

sku = Stripe::SKU.retrieve("sk_17YLrW2eZvKYlo2Czz70fPGC")
sku.metadata["key"] = "value"
sku.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

sku = stripe.SKU.retrieve("sk_17YLrW2eZvKYlo2Czz70fPGC")
sku.metadata["key"] = "value"
sku.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$sku = \Stripe\SKU::retrieve("sk_17YLrW2eZvKYlo2Czz70fPGC");
$sku->metadata["key"] = "value";
$sku->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

SKU sku = SKU.retrieve("sk_17YLrW2eZvKYlo2Czz70fPGC");
Map metadata = new HashMap();
metdata.put("key", "value");
Map params = new HashMap();
params.put("metadata", metadata);
sku.update(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.skus.update("sk_17YLrW2eZvKYlo2Czz70fPGC", {
  metadata: {key: "value"}
)
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p, err := sku.Update(
      "sk_17YLrW2eZvKYlo2Czz70fPGC",
      &stripe.SKUParams{Meta: map[string]string{"key": "value"}}
)
 
{
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
#<Stripe::SKU id=sku_7nxnrzcWC029db 0x00000a> JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
<SKU sku id=sku_7nxnrzcWC029db at 0x00000a> JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
Stripe\SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
com.stripe.model.SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
{
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}
&stripe.SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
    "key": "value"
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}

List all SKUs

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

Arguments

  • active optional

    Only return SKUs that are active or inactive (e.g. pass false to list all inactive products).

  • attributes optional

    Only return SKUs that have the specified key/value pairs in this partially constructed dictionary. Can be specified only if product is also supplied. For instance, if the associated product has attributes ["color", "size"], passing in attributes[color]=red returns all the SKUs for this product that have color set to red.

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

  • ids optional

    Only return SKUs with the given IDs.

  • in_stock optional

    Only return SKUs that are either in stock or out of stock (e.g. pass false to list all SKUs that are out of stock). If no value is provided, all SKUs are returned.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • product optional

    The ID of the product whose SKUs will be retrieved.

  • 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 arrayMapobjectmap with a data property that contains an array of up to limit SKUs, starting after SKU starting_after. Each entry in the array is a separate SKU object. If no more SKUs are available, the resulting array will be empty. If you provide a non-existent product ID, this request will returnraiseraisethrowthrowthrowreturn an an error. Similarly, if you try to filter products by an attribute that is not supported by the specified product, this request will returnraiseraisethrowthrowthrowreturn an an error.

GET https://api.stripe.com/v1/skus
Stripe::Sku.all
stripe.Sku.all()
\Stripe\Sku::all();
Sku.all(Map<String, Object> options);
stripe.skus.list();
sku.List()
 
curl https://api.stripe.com/v1/skus?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Sku.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Sku.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Sku::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> skuParams = new HashMap<String, Object>();
skuParams.put("limit", 3);

Sku.all(skuParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.skus.list(
  { limit: 3 },
  function(err, skus) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.SkuListParams{}
params.Filters.AddFilter("limit", "", "3")
i := sku.List(params)
for i.Next() {
  s := i.Sku()
}
 
{
  "object": "list",
  "url": "/v1/skus",
  "has_more": false,
  "data": [
    {
      "id": "sku_7nxnrzcWC029db",
      "object": "sku",
      "active": true,
      "attributes": {
        "size": "10ml",
        "nicotine": "0mg"
      },
      "created": 1454010926,
      "currency": "usd",
      "image": null,
      "inventory": {
        "quantity": null,
        "type": "infinite",
        "value": null
      },
      "livemode": false,
      "metadata": {
      },
      "package_dimensions": null,
      "price": 495,
      "product": "14540109231001",
      "updated": 1454010926
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/skus",
  "has_more": false,
  "data": [
    #<Stripe::SKU id=sku_7nxnrzcWC029db 0x00000a> JSON: {
      "id": "sku_7nxnrzcWC029db",
      "object": "sku",
      "active": true,
      "attributes": {
        "size": "10ml",
        "nicotine": "0mg"
      },
      "created": 1454010926,
      "currency": "usd",
      "image": null,
      "inventory": {
        "quantity": null,
        "type": "infinite",
        "value": null
      },
      "livemode": false,
      "metadata": {
      },
      "package_dimensions": null,
      "price": 495,
      "product": "14540109231001",
      "updated": 1454010926
    },
    #<Stripe::Sku[...] ...>,
    #<Stripe::Sku[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/skus",
  has_more: false,
  data: [
    <SKU sku id=sku_7nxnrzcWC029db at 0x00000a> JSON: {
      "id": "sku_7nxnrzcWC029db",
      "object": "sku",
      "active": true,
      "attributes": {
        "size": "10ml",
        "nicotine": "0mg"
      },
      "created": 1454010926,
      "currency": "usd",
      "image": null,
      "inventory": {
        "quantity": null,
        "type": "infinite",
        "value": null
      },
      "livemode": false,
      "metadata": {
      },
      "package_dimensions": null,
      "price": 495,
      "product": "14540109231001",
      "updated": 1454010926
    },
    <stripe.Sku[...] ...>,
    <stripe.Sku[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/skus",
  "has_more" => false,
  "data" => [
    [0] => Stripe\SKU JSON: {
      "id": "sku_7nxnrzcWC029db",
      "object": "sku",
      "active": true,
      "attributes": {
        "size": "10ml",
        "nicotine": "0mg"
      },
      "created": 1454010926,
      "currency": "usd",
      "image": null,
      "inventory": {
        "quantity": null,
        "type": "infinite",
        "value": null
      },
      "livemode": false,
      "metadata": {
      },
      "package_dimensions": null,
      "price": 495,
      "product": "14540109231001",
      "updated": 1454010926
    }
    [1] => <Stripe\Sku[...] ...>
    [2] => <Stripe\Sku[...] ...>
  ]
}
#<com.stripe.model.SkuCollection id=#> JSON: {
  "data": [
    com.stripe.model.SKU JSON: {
      "id": "sku_7nxnrzcWC029db",
      "object": "sku",
      "active": true,
      "attributes": {
        "size": "10ml",
        "nicotine": "0mg"
      },
      "created": 1454010926,
      "currency": "usd",
      "image": null,
      "inventory": {
        "quantity": null,
        "type": "infinite",
        "value": null
      },
      "livemode": false,
      "metadata": {
      },
      "package_dimensions": null,
      "price": 495,
      "product": "14540109231001",
      "updated": 1454010926
    },
    #<com.stripe.model.Sku[...] ...>,
    #<com.stripe.model.Sku[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/skus",
  "has_more": false,
  "data": [
    {
      "id": "sku_7nxnrzcWC029db",
      "object": "sku",
      "active": true,
      "attributes": {
        "size": "10ml",
        "nicotine": "0mg"
      },
      "created": 1454010926,
      "currency": "usd",
      "image": null,
      "inventory": {
        "quantity": null,
        "type": "infinite",
        "value": null
      },
      "livemode": false,
      "metadata": {
      },
      "package_dimensions": null,
      "price": 495,
      "product": "14540109231001",
      "updated": 1454010926
    },
    {...},
    {...}
  ]
}
&stripe.SKU JSON: {
  "id": "sku_7nxnrzcWC029db",
  "object": "sku",
  "active": true,
  "attributes": {
    "size": "10ml",
    "nicotine": "0mg"
  },
  "created": 1454010926,
  "currency": "usd",
  "image": null,
  "inventory": {
    "quantity": null,
    "type": "infinite",
    "value": null
  },
  "livemode": false,
  "metadata": {
  },
  "package_dimensions": null,
  "price": 495,
  "product": "14540109231001",
  "updated": 1454010926
}

Delete a SKU

Delete a SKU. Deleting a SKU is only possible until it has been used in an order.

Arguments

  • id required

    The identifier of the SKU to be deleted

Returns

Returns an object with a deleted parameter on success. Otherwise, this call returnsraisesraisesthrowsthrowsthrowsreturns an error 

DELETE https://api.stripe.com/v1/skus/{SKU_ID}
sku = Stripe::SKU.retrieve({SKU_ID})
sku.delete
sku = stripe.SKU.retrieve({SKU_ID})
sku.delete()
$sku = \Stripe\SKU::retrieve({SKU_ID});
$sku->delete();
SKU sku = SKU.retrieve({SKU_ID});
sku.delete();
stripe.skus.del({SKU_ID});
sku.Del({SKU_ID})
 
curl https://api.stripe.com/v1/skus/sku_7nxnrzcWC029db \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

sku = Stripe::SKU.retrieve("sku_7nxnrzcWC029db")
sku.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

sku = stripe.SKU.retrieve("sku_7nxnrzcWC029db")
sku.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$sku = \Stripe\SKU::retrieve("sku_7nxnrzcWC029db");
$sku->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

SKU sku = SKU.retrieve("sku_7nxnrzcWC029db");
sku.delete();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.skus.del(
  "sku_7nxnrzcWC029db",
  funcion(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := sku.Del(
      "sku_7nxnrzcWC029db",
)
 
{
  "deleted": true,
  "id": "sku_7nxnrzcWC029db"
}
#<Stripe::Object id=sku_7nxnrzcWC029db 0x00000a> JSON: {
  "deleted": true,
  "id": "sku_7nxnrzcWC029db"
}
<Object object id=sku_7nxnrzcWC029db at 0x00000a> JSON: {
  "deleted": true,
  "id": "sku_7nxnrzcWC029db"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "sku_7nxnrzcWC029db"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "sku_7nxnrzcWC029db"
}
{
  "deleted": true,
  "id": "sku_7nxnrzcWC029db"
}
&stripe.Object JSON: {
  "deleted": true,
  "id": "sku_7nxnrzcWC029db"
}

Coupons

A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons only apply to invoices; they do not apply to one-off charges.

The coupon object

Attributes

  • id string

  • object string , value is "coupon"

  • amount_off positive integer

    Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer.

  • created timestamp

  • currency currency

    If amount_off has been set, the currency of the amount to take off.

  • duration coupon duration string

    One of forever, once, and repeating. Describes how long a customer who applies this coupon will get the discount.

  • duration_in_months positive integer

    If duration is repeating, the number of months the coupon applies. Null if coupon duration is forever or once.

  • livemode boolean

  • max_redemptions positive integer

    Maximum number of times this coupon can be redeemed, in total, before it is no longer valid.

  • metadata #

    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": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
#<Stripe::Coupon id=Tfrf9ICh 0x00000a> JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
<Coupon coupon id=Tfrf9ICh at 0x00000a> JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
Stripe\Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
com.stripe.model.Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
{
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
&stripe.Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}

Create a coupon

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 to 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, in which case it must be 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 nullnilNonenullnullnullnull 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

    Unix 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/coupons
Stripe::Coupon.create
stripe.Coupon.create()
\Stripe\Coupon::create();
Coupon.create();
stripe.coupons.create();
coupon.New()
 
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=25OFF

require "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')
\Stripe\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'
}, function(err, coupon) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := coupon.New(&stripe.CouponParams{
  Percent: 25,
  Duration: "repeating",
  DurationPeriod: 3,
  ID: "250FF",
})
 
{
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
#<Stripe::Coupon id=Tfrf9ICh 0x00000a> JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
<Coupon coupon id=Tfrf9ICh at 0x00000a> JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
Stripe\Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
com.stripe.model.Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
{
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
&stripe.Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}

Retrieve a coupon

Retrieves the coupon with the given ID.

Arguments

  • coupon required

    The ID of the desired coupon.

Returns

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

curl https://api.stripe.com/v1/coupons/Tfrf9ICh \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Coupon.retrieve("Tfrf9ICh")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Coupon.retrieve("Tfrf9ICh")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Coupon::retrieve("Tfrf9ICh");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon.retrieve("Tfrf9ICh");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.retrieve(
  "Tfrf9ICh",
  function(err, coupon) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := coupon.Get("Tfrf9ICh", nil)
 
{
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
#<Stripe::Coupon id=Tfrf9ICh 0x00000a> JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
<Coupon coupon id=Tfrf9ICh at 0x00000a> JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
Stripe\Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
com.stripe.model.Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
{
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
&stripe.Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}

Update a coupon

Updates the metadata of a coupon. Other coupon details (currency, duration, amount_off) are, by design, not editable.

Arguments

  • id required

    The identifier of the coupon to be updated.

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    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.

Returns

The newly updated coupon object if the call succeeded. Otherwise, this call returnsraisesraisesthrowsthrowsthrowsreturns an error, such as if the coupon has been deleted. 

POST https://api.stripe.com/v1/coupons/{COUPON_ID}
coupon = Stripe::Coupon.retrieve({COUPON_ID})
coupon.metadata[{KEY}] = {VALUE}
coupon.save
coupon = stripe.Coupon.retrieve({COUPON_ID})
coupon.metadata[{KEY}] = {VALUE}
coupon.save()
$coupon = \Stripe\Coupon::retrieve({COUPON_ID});
$coupon->metadata[{KEY}] = {VALUE};
$coupon->save();
Coupon coupon = Coupon.retrieve({COUPON_ID});
Map metadata = new HashMap();
metdata.put({KEY}, {VALUE});
Map params = new HashMap();
params.put("metadata", metadata);
coupon.update(params);
stripe.coupons.update({COUPON_ID}, {
  metadata: {{KEY}: {VALUE}}
})
coupon.Update({COUPON_ID}, &stripe.CouponParams{Meta: map[string]string{{KEY}: {VALUE}}})
 
curl https://api.stripe.com/v1/coupons/Tfrf9ICh \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

coupon = Stripe::Coupon.retrieve("Tfrf9ICh")
coupon.metadata["key"] = "value"
coupon.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

coupon = stripe.Coupon.retrieve("Tfrf9ICh")
coupon.metadata["key"] = "value"
coupon.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$coupon = \Stripe\Coupon::retrieve("Tfrf9ICh");
$coupon->metadata["key"] = "value";
$coupon->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon coupon = Coupon.retrieve("Tfrf9ICh");
Map metadata = new HashMap();
metdata.put("key", "value");
Map params = new HashMap();
params.put("metadata", metadata);
coupon.update(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.update("Tfrf9ICh", {
  metadata: {key: "value"}
)
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := coupon.Update(
      "Tfrf9ICh",
      &stripe.CouponParams{Meta: map[string]string{"key": "value"}},
)
 
{
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
    "key": "value"
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
#<Stripe::Coupon id=Tfrf9ICh 0x00000a> JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
    "key": "value"
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
<Coupon coupon id=Tfrf9ICh at 0x00000a> JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
    "key": "value"
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
Stripe\Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
    "key": "value"
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
com.stripe.model.Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
    "key": "value"
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
{
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
    "key": "value"
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}
&stripe.Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
    "key": "value"
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}

Delete 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

  • coupon 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 returnsraisesraisesthrowsthrowsthrowsreturns 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})
coupon.Del({COUPON_ID})
 
curl https://api.stripe.com/v1/coupons/Tfrf9ICh \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cpn = Stripe::Coupon.retrieve("Tfrf9ICh")
cpn.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cpn = stripe.Coupon.retrieve("Tfrf9ICh")
cpn.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cpn = \Stripe\Coupon::retrieve("Tfrf9ICh");
$cpn->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon cpn = Coupon.retrieve("Tfrf9ICh");
cpn.delete();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.del("Tfrf9ICh")
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := coupon.Del("Tfrf9ICh")
 
{
  "deleted": true,
  "id": "Tfrf9ICh"
}
#<Stripe::Object id=Tfrf9ICh 0x00000a> JSON: {
  "deleted": true,
  "id": "Tfrf9ICh"
}
<Object object id=Tfrf9ICh at 0x00000a> JSON: {
  "deleted": true,
  "id": "Tfrf9ICh"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "Tfrf9ICh"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "Tfrf9ICh"
}
{
  "deleted": true,
  "id": "Tfrf9ICh"
}
nil

List all coupons

Returns a list of your coupons.

Arguments

  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • 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 arrayMapobjectmap 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 returnraiseraisethrowthrowthrowreturn an an error.

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

GET https://api.stripe.com/v1/coupons
Stripe::Coupon.all
stripe.Coupon.all()
\Stripe\Coupon::all();
Coupon.all(Map<String, Object> options);
stripe.coupons.list();
coupon.List()
 
curl https://api.stripe.com/v1/coupons?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Coupon.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Coupon.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Coupon::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> couponParams = new HashMap<String, Object>();
couponParams.put("limit", 3);

Coupon.all(couponParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.list(
  { limit: 3 },
  function(err, coupons) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CouponListParams{}
params.Filters.AddFilter("limit", "", "3")
i := coupon.List(params)
for i.Next() {
  c := i.Coupon()
}
 
{
  "object": "list",
  "url": "/v1/coupons",
  "has_more": false,
  "data": [
    {
      "id": "Tfrf9ICh",
      "object": "coupon",
      "amount_off": null,
      "created": 1452719554,
      "currency": "usd",
      "duration": "once",
      "duration_in_months": null,
      "livemode": false,
      "max_redemptions": null,
      "metadata": {
      },
      "percent_off": 75,
      "redeem_by": null,
      "times_redeemed": 0,
      "valid": true
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/coupons",
  "has_more": false,
  "data": [
    #<Stripe::Coupon id=Tfrf9ICh 0x00000a> JSON: {
      "id": "Tfrf9ICh",
      "object": "coupon",
      "amount_off": null,
      "created": 1452719554,
      "currency": "usd",
      "duration": "once",
      "duration_in_months": null,
      "livemode": false,
      "max_redemptions": null,
      "metadata": {
      },
      "percent_off": 75,
      "redeem_by": null,
      "times_redeemed": 0,
      "valid": true
    },
    #<Stripe::Coupon[...] ...>,
    #<Stripe::Coupon[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/coupons",
  has_more: false,
  data: [
    <Coupon coupon id=Tfrf9ICh at 0x00000a> JSON: {
      "id": "Tfrf9ICh",
      "object": "coupon",
      "amount_off": null,
      "created": 1452719554,
      "currency": "usd",
      "duration": "once",
      "duration_in_months": null,
      "livemode": false,
      "max_redemptions": null,
      "metadata": {
      },
      "percent_off": 75,
      "redeem_by": null,
      "times_redeemed": 0,
      "valid": true
    },
    <stripe.Coupon[...] ...>,
    <stripe.Coupon[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/coupons",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Coupon JSON: {
      "id": "Tfrf9ICh",
      "object": "coupon",
      "amount_off": null,
      "created": 1452719554,
      "currency": "usd",
      "duration": "once",
      "duration_in_months": null,
      "livemode": false,
      "max_redemptions": null,
      "metadata": {
      },
      "percent_off": 75,
      "redeem_by": null,
      "times_redeemed": 0,
      "valid": true
    }
    [1] => <Stripe\Coupon[...] ...>
    [2] => <Stripe\Coupon[...] ...>
  ]
}
#<com.stripe.model.CouponCollection id=#> JSON: {
  "data": [
    com.stripe.model.Coupon JSON: {
      "id": "Tfrf9ICh",
      "object": "coupon",
      "amount_off": null,
      "created": 1452719554,
      "currency": "usd",
      "duration": "once",
      "duration_in_months": null,
      "livemode": false,
      "max_redemptions": null,
      "metadata": {
      },
      "percent_off": 75,
      "redeem_by": null,
      "times_redeemed": 0,
      "valid": true
    },
    #<com.stripe.model.Coupon[...] ...>,
    #<com.stripe.model.Coupon[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/coupons",
  "has_more": false,
  "data": [
    {
      "id": "Tfrf9ICh",
      "object": "coupon",
      "amount_off": null,
      "created": 1452719554,
      "currency": "usd",
      "duration": "once",
      "duration_in_months": null,
      "livemode": false,
      "max_redemptions": null,
      "metadata": {
      },
      "percent_off": 75,
      "redeem_by": null,
      "times_redeemed": 0,
      "valid": true
    },
    {...},
    {...}
  ]
}
&stripe.Coupon JSON: {
  "id": "Tfrf9ICh",
  "object": "coupon",
  "amount_off": null,
  "created": 1452719554,
  "currency": "usd",
  "duration": "once",
  "duration_in_months": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
  },
  "percent_off": 75,
  "redeem_by": null,
  "times_redeemed": 0,
  "valid": true
}

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 string

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

  • start timestamp

    Date that the coupon was applied.

  • subscription string

    The subscription that this coupon is applied to, if it is applied to a particular subscription. 

{
  "object": "discount",
  "coupon": {
    "id": "Tfrf9ICh",
    "object": "coupon",
    "amount_off": null,
    "created": 1452719554,
    "currency": "usd",
    "duration": "once",
    "duration_in_months": null,
    "livemode": false,
    "max_redemptions": null,
    "metadata": {
    },
    "percent_off": 75,
    "redeem_by": null,
    "times_redeemed": 0,
    "valid": true
  },
  "customer": "cus_7oGjJvWit3N9Ps",
  "end": null,
  "start": 1407953279,
  "subscription": null
}
#<Stripe::Discount 0x00000a> JSON: {
  "object": "discount",
  "coupon": {
    "id": "Tfrf9ICh",
    "object": "coupon",
    "amount_off": null,
    "created": 1452719554,
    "currency": "usd",
    "duration": "once",
    "duration_in_months": null,
    "livemode": false,
    "max_redemptions": null,
    "metadata": {
    },
    "percent_off": 75,
    "redeem_by": null,
    "times_redeemed": 0,
    "valid": true
  },
  "customer": "cus_7oGjJvWit3N9Ps",
  "end": null,
  "start": 1407953279,
  "subscription": null
}
<Discount discount at 0x00000a> JSON: {
  "object": "discount",
  "coupon": {
    "id": "Tfrf9ICh",
    "object": "coupon",
    "amount_off": null,
    "created": 1452719554,
    "currency": "usd",
    "duration": "once",
    "duration_in_months": null,
    "livemode": false,
    "max_redemptions": null,
    "metadata": {
    },
    "percent_off": 75,
    "redeem_by": null,
    "times_redeemed": 0,
    "valid": true
  },
  "customer": "cus_7oGjJvWit3N9Ps",
  "end": null,
  "start": 1407953279,
  "subscription": null
}
Stripe\Discount JSON: {
  "object": "discount",
  "coupon": {
    "id": "Tfrf9ICh",
    "object": "coupon",
    "amount_off": null,
    "created": 1452719554,
    "currency": "usd",
    "duration": "once",
    "duration_in_months": null,
    "livemode": false,
    "max_redemptions": null,
    "metadata": {
    },
    "percent_off": 75,
    "redeem_by": null,
    "times_redeemed": 0,
    "valid": true
  },
  "customer": "cus_7oGjJvWit3N9Ps",
  "end": null,
  "start": 1407953279,
  "subscription": null
}
com.stripe.model.Discount JSON: {
  "object": "discount",
  "coupon": {
    "id": "Tfrf9ICh",
    "object": "coupon",
    "amount_off": null,
    "created": 1452719554,
    "currency": "usd",
    "duration": "once",
    "duration_in_months": null,
    "livemode": false,
    "max_redemptions": null,
    "metadata": {
    },
    "percent_off": 75,
    "redeem_by": null,
    "times_redeemed": 0,
    "valid": true
  },
  "customer": "cus_7oGjJvWit3N9Ps",
  "end": null,
  "start": 1407953279,
  "subscription": null
}
{
  "object": "discount",
  "coupon": {
    "id": "Tfrf9ICh",
    "object": "coupon",
    "amount_off": null,
    "created": 1452719554,
    "currency": "usd",
    "duration": "once",
    "duration_in_months": null,
    "livemode": false,
    "max_redemptions": null,
    "metadata": {
    },
    "percent_off": 75,
    "redeem_by": null,
    "times_redeemed": 0,
    "valid": true
  },
  "customer": "cus_7oGjJvWit3N9Ps",
  "end": null,
  "start": 1407953279,
  "subscription": null
}
&stripe.Discount JSON: {
  "object": "discount",
  "coupon": {
    "id": "Tfrf9ICh",
    "object": "coupon",
    "amount_off": null,
    "created": 1452719554,
    "currency": "usd",
    "duration": "once",
    "duration_in_months": null,
    "livemode": false,
    "max_redemptions": null,
    "metadata": {
    },
    "percent_off": 75,
    "redeem_by": null,
    "times_redeemed": 0,
    "valid": true
  },
  "customer": "cus_7oGjJvWit3N9Ps",
  "end": null,
  "start": 1407953279,
  "subscription": null
}

Delete a customer discount

Removes the currently applied discount on a customer.

Arguments

  • No arguments…

Returns

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

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/discount
cu = 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});
discount.Del({CUSTOMER_ID})
 
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/discount \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
cu.delete_discount
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
cu.delete_discount()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$cu->deleteDiscount();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
cu.deleteDiscount();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.deleteDiscount("cus_7oGjJvWit3N9Ps", function(err, confirmation) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := discount.Del("cus_7oGjJvWit3N9Ps")
 
{
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
#<Stripe::Object id=di_14R6AF2eZvKYlo2CNViIj0rs 0x00000a> JSON: {
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
<Object object id=di_14R6AF2eZvKYlo2CNViIj0rs at 0x00000a> JSON: {
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
{
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
nil

Delete a subscription discount

Removes the currently applied discount on a subscription.

Arguments

  • No arguments…

Returns

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

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}/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}).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});
discount.DelSub({CUSTOMER_ID}, {SUBSCRIPTION_ID})
 
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions/sub_7oH6r1H2fws6yk/discount \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
cu.subscriptions.retrieve("sub_7oH6r1H2fws6yk").delete_discount()
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
cu.subscriptions.retrieve("sub_7oH6r1H2fws6yk").delete_discount()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$cu->subscriptions->retrieve("sub_7oH6r1H2fws6yk")->deleteDiscount();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
cu.subscriptions.retrieve("sub_7oH6r1H2fws6yk").deleteDiscount();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.deleteSubscriptionDiscount("cus_7oGjJvWit3N9Ps", "sub_7oH6r1H2fws6yk", function(err, confirmation) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := discount.DelSub(
      "cus_7oGjJvWit3N9Ps",
      "sub_7oH6r1H2fws6yk",
)
 
{
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
#<Stripe::Object id=di_14R6AF2eZvKYlo2CNViIj0rs 0x00000a> JSON: {
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
<Object object id=di_14R6AF2eZvKYlo2CNViIj0rs at 0x00000a> JSON: {
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
{
  "deleted": true,
  "id": "di_14R6AF2eZvKYlo2CNViIj0rs"
}
nil

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"

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

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

  • attempt_count positive integer or zero

    Number of payment attempts made for this invoice, from the perspective of the payment retry schedule. Any payment attempt counts as the first attempt, and subsequently only automatic retries increment the attempt count. In other words, manual payment attempts after the first attempt do not affect the retry schedule.

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

  • charge string

    ID of the latest charge generated for this invoice, if any.

  • 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 string

  • date timestamp

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

  • forgiven boolean

    Whether or not the invoice has been forgiven. Forgiving an invoice instructs us to update the subscription status as if the invoice were succcessfully paid. Once an invoice has been forgiven, it cannot be unforgiven or reopened

  • lines list

    The individual line items that make up the invoice. lines is sorted as follows: invoice items in reverse chronological order, followed by the subscription, if any.

    child attributes

    • object string , value is "list"

    • data array, contains: invoice_line_item object

    • has_more boolean

    • total_count positive integer or zero

      The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

    • url string

      The URL where this list can be accessed.

  • livemode boolean

  • metadata #

    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.

  • next_payment_attempt timestamp

    The time at which payment will next be attempted.

  • 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 during which invoice items were added to this invoice

  • period_start timestamp

    Start of the usage period during which invoice items were added to this invoice

  • receipt_number string

    This is the transaction number that appears on email receipts sent for this invoice.

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

  • statement_descriptor string

    Extra information about an invoice for the customer’s credit card statement.

  • subscription string

    The subscription that this invoice was prepared for, if any.

  • subscription_proration_date integer

    Only set for upcoming invoices that preview prorations. The time used to calculate prorations.

  • subtotal integer

    Total of all subscriptions, invoice items, and prorations on the invoice before any discount is applied

  • tax integer

    The amount of tax included in the total, calculated from tax_percent and the subtotal. If no tax_percent is defined, this value will be null.

  • tax_percent decimal

    This percentage of the subtotal has been added to the total amount of the invoice, including invoice line items and discounts. This field is inherited from the subscription’s tax_percent field, but can be changed before the invoice is paid. This field defaults to null.

  • total integer

    Total after discount

  • webhooks_delivered_at timestamp

    The time at which webhooks for this invoice were successfully delivered (if the invoice had no webhooks to deliver, this will match date). Invoice payment is delayed until webhooks are delivered, or until all webhook delivery attempts have been exhausted. 

{
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
#<Stripe::Invoice id=in_17YeNs2eZvKYlo2ChzccUXmN 0x00000a> JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
<Invoice invoice id=in_17YeNs2eZvKYlo2ChzccUXmN at 0x00000a> JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
Stripe\Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
com.stripe.model.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
{
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
&stripe.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}

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 , value is "invoice_line_item"

    line_item

  • amount integer

    The amount, in cents

  • currency currency

  • description string

    A text description of the line item, if the line item is an invoice item

  • discountable boolean

    If true, discounts will apply to this line item. Always false for prorations.

  • livemode boolean

    Whether or not this is a test line item

  • metadata #

    Key-value pairs attached to object that underlies this line item (either subscription or invoice item)

  • period hash

    The period this line_item covers. For subscription line items, this is the subscription period. For prorations, this starts when the proration was calculated, and ends at the period end of the subscription. For invoice items, this is the time at which the invoice item was created, so the period start and end are the same time.

  • plan hash, plan object

    The plan of the subscription, if the line item is a subscription or a proration

  • proration boolean

    Whether or not this is a proration

  • quantity integer

    The quantity of the subscription, if the line item is a subscription or a proration

  • subscription string

    When type is invoiceitem, the subscription that the invoice item pertains to, if any. Left blank when type is already subscription, as it’d be redundant with id.

  • type string

    A string identifying the type of the source of this line item, either an invoiceitem or a subscription 

{
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "line_item",
  "amount": -100,
  "currency": "usd",
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1453650744
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8",
  "type": "invoiceitem"
}
#<Stripe::LineItem id=ii_17WqA82eZvKYlo2CSYkrXgRX 0x00000a> JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "line_item",
  "amount": -100,
  "currency": "usd",
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1453650744
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8",
  "type": "invoiceitem"
}
<LineItem line_item id=ii_17WqA82eZvKYlo2CSYkrXgRX at 0x00000a> JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "line_item",
  "amount": -100,
  "currency": "usd",
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1453650744
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8",
  "type": "invoiceitem"
}
Stripe\LineItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "line_item",
  "amount": -100,
  "currency": "usd",
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1453650744
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8",
  "type": "invoiceitem"
}
com.stripe.model.LineItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "line_item",
  "amount": -100,
  "currency": "usd",
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1453650744
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8",
  "type": "invoiceitem"
}
{
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "line_item",
  "amount": -100,
  "currency": "usd",
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1453650744
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8",
  "type": "invoiceitem"
}
&stripe.LineItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "line_item",
  "amount": -100,
  "currency": "usd",
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1453650744
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8",
  "type": "invoiceitem"
}

Create 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 or the Stripe-Account header in order to take an application fee. For more information, see the application fees documentation.

  • description optional

  • metadata optional

  • statement_descriptor optional

    Extra information about a charge for the customer’s credit card statement.

  • 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 other subscriptions.

  • tax_percent optional

    The percent tax rate applied to the invoice, represented as a decimal number.

Returns

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

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

POST https://api.stripe.com/v1/invoices
Stripe::Invoice.create()
stripe.Invoice.create()
\Stripe\Invoice::create();
Invoice.create();
stripe.invoices.create();
invoice.New()
 
curl https://api.stripe.com/v1/invoices \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d customer=cus_7oGjJvWit3N9Ps

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Invoice.create(
    :customer => "cus_7oGjJvWit3N9Ps"
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.create(
    customer="cus_7oGjJvWit3N9Ps"
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Invoice::create(array(
    "customer" => "cus_7oGjJvWit3N9Ps"
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> invoiceParams = new HashMap<String, Object>();
invoiceParams.put("customer", "cus_7oGjJvWit3N9Ps");

Invoice.create(invoiceParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoices.create({
  customer: "cus_7oGjJvWit3N9Ps"
}, function(err, invoice) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

i, err := invoice.New(&stripe.InvoiceParams{Customer: "cus_7oGjJvWit3N9Ps"})
 
{
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
#<Stripe::Invoice id=in_17YeNs2eZvKYlo2ChzccUXmN 0x00000a> JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
<Invoice invoice id=in_17YeNs2eZvKYlo2ChzccUXmN at 0x00000a> JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
Stripe\Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
com.stripe.model.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
{
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
&stripe.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}

Retrieve an invoice

Retrieves the invoice with the given ID.

Arguments

  • invoice required

    The identifier of the desired invoice.

Returns

Returns an invoice object if a valid invoice ID was provided. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an 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 Unix 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 nullnilNonenullnullnullnull.

curl https://api.stripe.com/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Invoice::retrieve("in_17YeNs2eZvKYlo2ChzccUXmN");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoices.retrieve(
  "in_17YeNs2eZvKYlo2ChzccUXmN",
  function(err, invoice) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

i, err := invoice.Get("in_17YeNs2eZvKYlo2ChzccUXmN", nil)
 
{
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
#<Stripe::Invoice id=in_17YeNs2eZvKYlo2ChzccUXmN 0x00000a> JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
<Invoice invoice id=in_17YeNs2eZvKYlo2ChzccUXmN at 0x00000a> JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
Stripe\Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
com.stripe.model.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
{
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
&stripe.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}

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

  • invoice 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

    The maximum number of line items to return

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

  • subscription_plan optional

  • subscription_prorate optional

  • subscription_proration_date optional

  • subscription_quantity optional

  • subscription_trial_end optional

Returns

Returns a list of line_item objects. 

GET https://api.stripe.com/v1/invoices/{INVOICE_ID}/lines
Stripe::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});
invoices.ListLines(&stripe.InvoiceLineListParams{Id: {INVOICE_ID}})
 
curl https://api.stripe.com/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines?limit=5 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN").lines.all({
  :limit => 5})
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN").lines.all(
  limit=5)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Invoice::retrieve("in_17YeNs2eZvKYlo2ChzccUXmN")->lines->all(array(
  'limit'=>5));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Invoice inv = Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN");
Map<String, Object> lineParams = new HashMap<String, Object>();
lineParams.put("limit", 5);
InvoiceLineItemCollection lines = inv.getLines().all(lineParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoices.retrieveLines(
  "in_17YeNs2eZvKYlo2ChzccUXmN",
  { limit: 5 },
  function(err, lines) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.InvoiceLineListParams{Id: "in_17YeNs2eZvKYlo2ChzccUXmN"}
params.Filters.AddFilter("limit", "", "5")
i := invoice.ListLines(params)
for i.Next() {
  line := i.InvoiceItem()
}
 
{
  "object": "list",
  "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines",
  "has_more": false,
  "data": [
    {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "line_item",
      "amount": -100,
      "currency": "usd",
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1453650744
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8",
      "type": "invoiceitem"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines",
  "has_more": false,
  "data": [
    #<Stripe::LineItem id=ii_17WqA82eZvKYlo2CSYkrXgRX 0x00000a> JSON: {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "line_item",
      "amount": -100,
      "currency": "usd",
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1453650744
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8",
      "type": "invoiceitem"
    },
    #<Stripe::LineItem[...] ...>,
    #<Stripe::LineItem[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines",
  has_more: false,
  data: [
    <LineItem line_item id=ii_17WqA82eZvKYlo2CSYkrXgRX at 0x00000a> JSON: {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "line_item",
      "amount": -100,
      "currency": "usd",
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1453650744
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8",
      "type": "invoiceitem"
    },
    <stripe.LineItem[...] ...>,
    <stripe.LineItem[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines",
  "has_more" => false,
  "data" => [
    [0] => Stripe\LineItem JSON: {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "line_item",
      "amount": -100,
      "currency": "usd",
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1453650744
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8",
      "type": "invoiceitem"
    }
    [1] => <Stripe\LineItem[...] ...>
    [2] => <Stripe\LineItem[...] ...>
  ]
}
#<com.stripe.model.InvoiceLineItemCollection id=#> JSON: {
  "data": [
    com.stripe.model.LineItem JSON: {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "line_item",
      "amount": -100,
      "currency": "usd",
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1453650744
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8",
      "type": "invoiceitem"
    },
    #<com.stripe.model.InvoiceLineItem[...] ...>,
    #<com.stripe.model.InvoiceLineItem[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines",
  "has_more": false,
  "data": [
    {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "line_item",
      "amount": -100,
      "currency": "usd",
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1453650744
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8",
      "type": "invoiceitem"
    },
    {...},
    {...}
  ]
}
&stripe.LineItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "line_item",
  "amount": -100,
  "currency": "usd",
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1453650744
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8",
  "type": "invoiceitem"
}

Retrieve an upcoming invoice

At any time, you can preview 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.

Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer’s discount.

You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass a proration_date parameter when doing the actual subscription update. The value passed in should be the same as the subscription_proration_date returned on the upcoming invoice resource. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start] is equal to the subscription_proration_date on the upcoming invoice resource.

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, but a subscription_plan is provided, you will preview creating a subscription to that plan. If neither subscription nor subscription_plan is provided, you will retrieve the next upcoming invoice from among the customer’s subscriptions.

  • subscription_plan optional

    If set, the invoice returned will preview updating the subscription given to this plan, or creating a new subscription to this plan if no subscription is given.

  • subscription_prorate optional

    If previewing an update to a subscription, this decides whether the preview will show the result of applying prorations or not. If set, one of subscription_plan or subscription, and one of subscription_plan, subscription_quantity or subscription_trial_end are required.

  • subscription_proration_date optional

    If previewing an update to a subscription, and doing proration, subscription_proration_date forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period, and cannot be before the subscription was on its current plan.If set, subscription, and one of subscription_plan, subscription_quantity or subscription_trial_end are required. Also, subscription_proration cannot be set to false.

  • subscription_quantity optional

    If provided, the invoice returned will preview updating or creating a subscription with that quantity. If set, one of subscription_plan or subscription is required.

  • subscription_trial_end optional

    If provided, the invoice returned will preview updating or creating a subscripton with that trial end. If set, one of subscription_plan or subscription is required.

Returns

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

GET https://api.stripe.com/v1/invoices/upcoming
Stripe::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})
invoice.GetNext(&stripe.InvoiceParams{Customer: {CUSTOMER_ID}})
 
curl https://api.stripe.com/v1/invoices/upcoming?customer=cus_7oGjJvWit3N9Ps \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Invoice.upcoming(:customer => "cus_7oGjJvWit3N9Ps")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.upcoming(customer="cus_7oGjJvWit3N9Ps")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Invoice::upcoming(array("customer" => "cus_7oGjJvWit3N9Ps"));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> invoiceParams = new HashMap<String, Object>();
invoiceParams.put("customer", "cus_7oGjJvWit3N9Ps");

Invoice.upcoming(invoiceParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoices.retrieveUpcoming(
  "cus_7oGjJvWit3N9Ps",
  function(err, upcoming) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

i, err := invoice.GetNext(&stripe.InvoiceParams{Customer: "cus_7oGjJvWit3N9Ps"})
 
{
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "sub_6zK9t4Kq4WviFQ",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1454081891,
          "end": 1456760291
        },
        "plan": {
          "id": "Premium Trial",
          "object": "plan",
          "amount": 0,
          "created": 1441955384,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Premium Trial",
          "statement_descriptor": null,
          "trial_period_days": 14
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
#<Stripe::Invoice 0x00000a> JSON: {
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "sub_6zK9t4Kq4WviFQ",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1454081891,
          "end": 1456760291
        },
        "plan": {
          "id": "Premium Trial",
          "object": "plan",
          "amount": 0,
          "created": 1441955384,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Premium Trial",
          "statement_descriptor": null,
          "trial_period_days": 14
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
<Invoice invoice at 0x00000a> JSON: {
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "sub_6zK9t4Kq4WviFQ",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1454081891,
          "end": 1456760291
        },
        "plan": {
          "id": "Premium Trial",
          "object": "plan",
          "amount": 0,
          "created": 1441955384,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Premium Trial",
          "statement_descriptor": null,
          "trial_period_days": 14
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
Stripe\Invoice JSON: {
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "sub_6zK9t4Kq4WviFQ",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1454081891,
          "end": 1456760291
        },
        "plan": {
          "id": "Premium Trial",
          "object": "plan",
          "amount": 0,
          "created": 1441955384,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Premium Trial",
          "statement_descriptor": null,
          "trial_period_days": 14
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
com.stripe.model.Invoice JSON: {
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "sub_6zK9t4Kq4WviFQ",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1454081891,
          "end": 1456760291
        },
        "plan": {
          "id": "Premium Trial",
          "object": "plan",
          "amount": 0,
          "created": 1441955384,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Premium Trial",
          "statement_descriptor": null,
          "trial_period_days": 14
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
{
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "sub_6zK9t4Kq4WviFQ",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1454081891,
          "end": 1456760291
        },
        "plan": {
          "id": "Premium Trial",
          "object": "plan",
          "amount": 0,
          "created": 1441955384,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Premium Trial",
          "statement_descriptor": null,
          "trial_period_days": 14
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
&stripe.Invoice JSON: {
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "sub_6zK9t4Kq4WviFQ",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1454081891,
          "end": 1456760291
        },
        "plan": {
          "id": "Premium Trial",
          "object": "plan",
          "amount": 0,
          "created": 1441955384,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Premium Trial",
          "statement_descriptor": null,
          "trial_period_days": 14
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "has_more": false,
    "total_count": 1,
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}

Update 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 or the Stripe-Account header 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

  • forgiven optional

    Boolean representing whether an invoice is forgiven or not. To forgive an invoice, pass true. Forgiving an invoice instructs us to update the subscription status as if the invoice were succcessfully paid. Once an invoice has been forgiven, it cannot be unforgiven or reopened.

  • metadata optional

  • statement_descriptor optional

    Extra information about a charge for the customer’s credit card statement.

  • tax_percent optional

    The percent tax rate applied to the invoice, represented as a decimal number. The tax rate of a paid or forgiven invoice cannot be changed.

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.update({INVOICE_ID}, {
  closed: true,
  ...
});
invoice.Update({INVOICE_ID}, &stripe.InvoiceParams{Closed: true})
 
curl https://api.stripe.com/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d closed=true

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

invoice = Stripe::Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN")
invoice.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

invoice = stripe.Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN")
invoice.closed = True
invoice.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$invoice = \Stripe\Invoice::retrieve("in_17YeNs2eZvKYlo2ChzccUXmN");
$invoice->closed = true
$invoice->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Invoice invoice = Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN");
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_17YeNs2eZvKYlo2ChzccUXmN",
  {
    closed: true
  },
  function(err, invoice) {
    // asynchronously called
  }
)
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

i, err := invoice.Update(
  "in_17YeNs2eZvKYlo2ChzccUXmN",
  &stripe.InvoiceParams{Closed: true}
)
 
{
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": true,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
#<Stripe::Invoice id=in_17YeNs2eZvKYlo2ChzccUXmN 0x00000a> JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": true,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
<Invoice invoice id=in_17YeNs2eZvKYlo2ChzccUXmN at 0x00000a> JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": true,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
Stripe\Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": true,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
com.stripe.model.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": true,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
{
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": true,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}
&stripe.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": true,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}

Pay 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

  • invoice required

    ID of invoice to pay.

Returns

Returns the invoice object.

POST https://api.stripe.com/v1/invoices/{INVOICE_ID}/pay
invoice = 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});
invoice.Pay({INVOICE_ID})
 
curl https://api.stripe.com/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/pay \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

invoice = Stripe::Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN")
invoice.pay
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

invoice = stripe.Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN")
invoice.pay()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$invoice = \Stripe\Invoice::retrieve("in_17YeNs2eZvKYlo2ChzccUXmN");
$invoice->pay();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

invoice = Invoice.retrieve("in_17YeNs2eZvKYlo2ChzccUXmN");
invoice.pay();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoices.pay("in_17YeNs2eZvKYlo2ChzccUXmN", function(err, invoice) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

i, err := invoice.Pay("in_17YeNs2eZvKYlo2ChzccUXmN", nil)
 
{
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": true,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": true,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141,
  "last_payment_attempt": null
}
#<Stripe::Invoice id=in_17YeNs2eZvKYlo2ChzccUXmN 0x00000a> JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": true,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": true,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141,
  "last_payment_attempt": null
}
<Invoice invoice id=in_17YeNs2eZvKYlo2ChzccUXmN at 0x00000a> JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": true,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": true,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141,
  "last_payment_attempt": null
}
Stripe\Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": true,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": true,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141,
  "last_payment_attempt": null
}
com.stripe.model.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": true,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": true,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141,
  "last_payment_attempt": null
}
{
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": true,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": true,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141,
  "last_payment_attempt": null
}
&stripe.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": true,
  "charge": "ch_17YeVf2eZvKYlo2CbSkw0Av7",
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
        "object": "line_item",
        "amount": 0,
        "currency": "usd",
        "description": "Unused time on Foo after 24 Jan 2016",
        "discountable": false,
        "livemode": false,
        "metadata": {
        },
        "period": {
          "start": 1453650744,
          "end": 1453650744
        },
        "plan": {
          "id": "25439foo1453650728",
          "object": "plan",
          "amount": 100,
          "created": 1453650733,
          "currency": "usd",
          "interval": "week",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Foo",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": true,
        "quantity": 1,
        "subscription": "sub_7mOyPHYn697do8",
        "type": "invoiceitem"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": true,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141,
  "last_payment_attempt": null
}

List all 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 dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object date field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the date field is after this timestamp.

    • gte optional

      Return values where the date field is after or equal to this timestamp.

    • lt optional

      Return values where the date field is before this timestamp.

    • lte optional

      Return values where the date field is before or equal to this timestamp.

  • 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 arrayMapobjectmap with a data property that contains an array of up to limit invoices, starting after invoice starting_after. Each entry in the array is a separate invoice object. If no more invoices are available, the resulting array will be empty. ReturnsRaisesRaisesThrowsThrowsThrowsReturns an an error if the customer ID is invalid.

GET https://api.stripe.com/v1/invoices
Stripe::Invoice.all
stripe.Invoice.all()
\Stripe\Invoice::all();
Invoice.all(Map<String, Object> options);
stripe.invoices.list();
invoice.List()
 
curl https://api.stripe.com/v1/invoices?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Invoice.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Invoice::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> invoiceParams = new HashMap<String, Object>();
invoiceParams.put("limit", 3);

Invoice.all(invoiceParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoices.list(
  { limit: 3 },
  function(err, invoices) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.InvoiceListParams{}
params.Filters.AddFilter("limit", "", "3")
i := invoice.List(params)
for i.Next() {
  i := i.Invoice()
}
 
{
  "object": "list",
  "url": "/v1/invoices",
  "has_more": false,
  "data": [
    {
      "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": false,
      "charge": null,
      "closed": false,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1454082124,
      "description": null,
      "discount": null,
      "ending_balance": null,
      "forgiven": false,
      "lines": {
        "data": [
          {
            "id": "sub_7oH6r1H2fws6yk",
            "object": "line_item",
            "amount": 2000,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": true,
            "metadata": {
            },
            "period": {
              "start": 1456761177,
              "end": 1459266777
            },
            "plan": {
              "id": "gold2132",
              "object": "plan",
              "amount": 2000,
              "created": 1386249594,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Gold ",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "total_count": 1,
        "object": "list",
        "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": 1454085724,
      "paid": false,
      "period_end": 1454081891,
      "period_start": 1451403491,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_6zK9t4Kq4WviFQ",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1454082141
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/invoices",
  "has_more": false,
  "data": [
    #<Stripe::Invoice id=in_17YeNs2eZvKYlo2ChzccUXmN 0x00000a> JSON: {
      "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": false,
      "charge": null,
      "closed": false,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1454082124,
      "description": null,
      "discount": null,
      "ending_balance": null,
      "forgiven": false,
      "lines": {
        "data": [
          {
            "id": "sub_7oH6r1H2fws6yk",
            "object": "line_item",
            "amount": 2000,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": true,
            "metadata": {
            },
            "period": {
              "start": 1456761177,
              "end": 1459266777
            },
            "plan": {
              "id": "gold2132",
              "object": "plan",
              "amount": 2000,
              "created": 1386249594,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Gold ",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "total_count": 1,
        "object": "list",
        "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": 1454085724,
      "paid": false,
      "period_end": 1454081891,
      "period_start": 1451403491,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_6zK9t4Kq4WviFQ",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1454082141
    },
    #<Stripe::Invoice[...] ...>,
    #<Stripe::Invoice[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/invoices",
  has_more: false,
  data: [
    <Invoice invoice id=in_17YeNs2eZvKYlo2ChzccUXmN at 0x00000a> JSON: {
      "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": false,
      "charge": null,
      "closed": false,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1454082124,
      "description": null,
      "discount": null,
      "ending_balance": null,
      "forgiven": false,
      "lines": {
        "data": [
          {
            "id": "sub_7oH6r1H2fws6yk",
            "object": "line_item",
            "amount": 2000,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": true,
            "metadata": {
            },
            "period": {
              "start": 1456761177,
              "end": 1459266777
            },
            "plan": {
              "id": "gold2132",
              "object": "plan",
              "amount": 2000,
              "created": 1386249594,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Gold ",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "total_count": 1,
        "object": "list",
        "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": 1454085724,
      "paid": false,
      "period_end": 1454081891,
      "period_start": 1451403491,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_6zK9t4Kq4WviFQ",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1454082141
    },
    <stripe.Invoice[...] ...>,
    <stripe.Invoice[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/invoices",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Invoice JSON: {
      "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": false,
      "charge": null,
      "closed": false,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1454082124,
      "description": null,
      "discount": null,
      "ending_balance": null,
      "forgiven": false,
      "lines": {
        "data": [
          {
            "id": "sub_7oH6r1H2fws6yk",
            "object": "line_item",
            "amount": 2000,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": true,
            "metadata": {
            },
            "period": {
              "start": 1456761177,
              "end": 1459266777
            },
            "plan": {
              "id": "gold2132",
              "object": "plan",
              "amount": 2000,
              "created": 1386249594,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Gold ",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "total_count": 1,
        "object": "list",
        "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": 1454085724,
      "paid": false,
      "period_end": 1454081891,
      "period_start": 1451403491,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_6zK9t4Kq4WviFQ",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1454082141
    }
    [1] => <Stripe\Invoice[...] ...>
    [2] => <Stripe\Invoice[...] ...>
  ]
}
#<com.stripe.model.InvoiceCollection id=#> JSON: {
  "data": [
    com.stripe.model.Invoice JSON: {
      "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": false,
      "charge": null,
      "closed": false,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1454082124,
      "description": null,
      "discount": null,
      "ending_balance": null,
      "forgiven": false,
      "lines": {
        "data": [
          {
            "id": "sub_7oH6r1H2fws6yk",
            "object": "line_item",
            "amount": 2000,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": true,
            "metadata": {
            },
            "period": {
              "start": 1456761177,
              "end": 1459266777
            },
            "plan": {
              "id": "gold2132",
              "object": "plan",
              "amount": 2000,
              "created": 1386249594,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Gold ",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "total_count": 1,
        "object": "list",
        "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": 1454085724,
      "paid": false,
      "period_end": 1454081891,
      "period_start": 1451403491,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_6zK9t4Kq4WviFQ",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1454082141
    },
    #<com.stripe.model.Invoice[...] ...>,
    #<com.stripe.model.Invoice[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/invoices",
  "has_more": false,
  "data": [
    {
      "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
      "object": "invoice",
      "amount_due": 0,
      "application_fee": null,
      "attempt_count": 0,
      "attempted": false,
      "charge": null,
      "closed": false,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1454082124,
      "description": null,
      "discount": null,
      "ending_balance": null,
      "forgiven": false,
      "lines": {
        "data": [
          {
            "id": "sub_7oH6r1H2fws6yk",
            "object": "line_item",
            "amount": 2000,
            "currency": "usd",
            "description": null,
            "discountable": true,
            "livemode": true,
            "metadata": {
            },
            "period": {
              "start": 1456761177,
              "end": 1459266777
            },
            "plan": {
              "id": "gold2132",
              "object": "plan",
              "amount": 2000,
              "created": 1386249594,
              "currency": "usd",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {
              },
              "name": "Gold ",
              "statement_descriptor": null,
              "trial_period_days": null
            },
            "proration": false,
            "quantity": 1,
            "subscription": null,
            "type": "subscription"
          }
        ],
        "total_count": 1,
        "object": "list",
        "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
      },
      "livemode": false,
      "metadata": {
      },
      "next_payment_attempt": 1454085724,
      "paid": false,
      "period_end": 1454081891,
      "period_start": 1451403491,
      "receipt_number": null,
      "starting_balance": 0,
      "statement_descriptor": null,
      "subscription": "sub_6zK9t4Kq4WviFQ",
      "subtotal": 0,
      "tax": null,
      "tax_percent": null,
      "total": 0,
      "webhooks_delivered_at": 1454082141
    },
    {...},
    {...}
  ]
}
&stripe.Invoice JSON: {
  "id": "in_17YeNs2eZvKYlo2ChzccUXmN",
  "object": "invoice",
  "amount_due": 0,
  "application_fee": null,
  "attempt_count": 0,
  "attempted": false,
  "charge": null,
  "closed": false,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1454082124,
  "description": null,
  "discount": null,
  "ending_balance": null,
  "forgiven": false,
  "lines": {
    "data": [
      {
        "id": "sub_7oH6r1H2fws6yk",
        "object": "line_item",
        "amount": 2000,
        "currency": "usd",
        "description": null,
        "discountable": true,
        "livemode": true,
        "metadata": {
        },
        "period": {
          "start": 1456761177,
          "end": 1459266777
        },
        "plan": {
          "id": "gold2132",
          "object": "plan",
          "amount": 2000,
          "created": 1386249594,
          "currency": "usd",
          "interval": "month",
          "interval_count": 1,
          "livemode": false,
          "metadata": {
          },
          "name": "Gold ",
          "statement_descriptor": null,
          "trial_period_days": null
        },
        "proration": false,
        "quantity": 1,
        "subscription": null,
        "type": "subscription"
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_17YeNs2eZvKYlo2ChzccUXmN/lines"
  },
  "livemode": false,
  "metadata": {
  },
  "next_payment_attempt": 1454085724,
  "paid": false,
  "period_end": 1454081891,
  "period_start": 1451403491,
  "receipt_number": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "subscription": "sub_6zK9t4Kq4WviFQ",
  "subtotal": 0,
  "tax": null,
  "tax_percent": null,
  "total": 0,
  "webhooks_delivered_at": 1454082141
}

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"

  • amount integer

  • currency currency

  • customer string

  • date timestamp

  • description string

  • discountable boolean

    If true, discounts will apply to this invoice item. Always false for prorations.

  • invoice string

  • livemode boolean

  • metadata #

    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.

  • period hash

  • plan hash, plan object

    If the invoice item is a proration, the plan of the subscription that the proration was computed for.

  • proration boolean

    Whether or not the invoice item was created automatically as a proration adjustment when the customer switched plans

  • quantity integer

    If the invoice item is a proration, the quantity of the subscription that the proration was computed for.

  • subscription string

    The subscription that this invoice item has been created for, if any. 

{
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
#<Stripe::InvoiceItem id=ii_17WqA82eZvKYlo2CSYkrXgRX 0x00000a> JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
<InvoiceItem invoiceitem id=ii_17WqA82eZvKYlo2CSYkrXgRX at 0x00000a> JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
Stripe\InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
com.stripe.model.InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
{
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
&stripe.InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}

Create an invoice item

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

Arguments

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

  • customer required

    The ID of the customer who will be billed when this invoice item is billed.

  • 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 nullnilNonenullnullnullnull and then saving.

  • discountable optional

    Controls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items.

  • 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, attempted or closed.

  • metadata optional

    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. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

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

Returns

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

POST https://api.stripe.com/v1/invoiceitems
Stripe::InvoiceItem.create()
stripe.InvoiceItem.create()
\Stripe\InvoiceItem::create();
InvoiceItem.create();
stripe.invoiceItems.create();
invoiceitem.New()
 
curl https://api.stripe.com/v1/invoiceitems \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d customer=cus_7oGjJvWit3N9Ps \
   -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_7oGjJvWit3N9Ps",
    :amount => 1000,
    :currency => "usd",
    :description => "One-time setup fee"
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.InvoiceItem.create(
    customer="cus_7oGjJvWit3N9Ps",
    amount=1000,
    currency="usd",
    description="One-time setup fee")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\InvoiceItem::create(array(
    "customer" => "cus_7oGjJvWit3N9Ps",
    "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_7oGjJvWit3N9Ps");
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_7oGjJvWit3N9Ps",
  amount: 1000,
  currency: "usd",
  description: "One-time setup fee"
}, function(err, invoiceItem) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ii, err := invoiceitem.New(&stripe.InvoiceItemParams{
  Customer: "cus_7oGjJvWit3N9Ps",
  Amount: 1000,
  Currency: "usd",
  Desc: "One-time setup fee",
},)
 
{
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
#<Stripe::InvoiceItem id=ii_17WqA82eZvKYlo2CSYkrXgRX 0x00000a> JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
<InvoiceItem invoiceitem id=ii_17WqA82eZvKYlo2CSYkrXgRX at 0x00000a> JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
Stripe\InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
com.stripe.model.InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
{
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
&stripe.InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}

Retrieve an invoice item

Retrieves the invoice item with the given ID.

Arguments

  • invoiceitem required

    The ID of the desired invoice item.

Returns

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

curl https://api.stripe.com/v1/invoiceitems/ii_17WqA82eZvKYlo2CSYkrXgRX \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::InvoiceItem.retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.InvoiceItem.retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\InvoiceItem::retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

InvoiceItem.retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoiceItems.retrieve(
  "ii_17WqA82eZvKYlo2CSYkrXgRX",
  function(err, invoiceitem) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

i, err := invoiceitem.Get("ii_17WqA82eZvKYlo2CSYkrXgRX", nil)
 
{
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
#<Stripe::InvoiceItem id=ii_17WqA82eZvKYlo2CSYkrXgRX 0x00000a> JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
<InvoiceItem invoiceitem id=ii_17WqA82eZvKYlo2CSYkrXgRX at 0x00000a> JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
Stripe\InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
com.stripe.model.InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
{
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
&stripe.InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}

Update 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 nullnilNonenullnullnullnull and then saving.

  • discountable optional

    Controls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items. Cannot be set to true for prorations.

  • 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 nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.

Returns

The updated invoice item object is returned upon success. Otherwise, this call returnsraisesraisesthrowsthrowsthrowsreturns 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} })
invoiceitem.Update({INVOICEITEM_ID}, &stripe.InvoiceItemParams{Amount: {AMOUNT}})
 
curl https://api.stripe.com/v1/invoiceitems/ii_17WqA82eZvKYlo2CSYkrXgRX \
   -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_17WqA82eZvKYlo2CSYkrXgRX")
ii.amount = 1500
ii.description = "Customer for test@example.com"
ii.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ii = stripe.InvoiceItem.retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX")
ii.amount = 1500
ii.description = "Customer for test@example.com"
ii.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ii = \Stripe\InvoiceItem::retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX");
$ii->amount = 1500;
$ii->description = "Customer for test@example.com";
$ii->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

InvoiceItem ii = InvoiceItem.retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX");
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_17WqA82eZvKYlo2CSYkrXgRX",
  {
    amount: 1500,
    description: "Customer for test@example.com"
  },
  function(err, invoiceItem) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ii, err := invoiceitem.Update(
  "ii_17WqA82eZvKYlo2CSYkrXgRX",
  &stripe.InvoiceItemParams{
    Amount: 1500,
    Desc: "Customer for test@example.com",
  },)
 
{
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 1500,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Customer for test@example.com",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
#<Stripe::InvoiceItem id=ii_17WqA82eZvKYlo2CSYkrXgRX 0x00000a> JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 1500,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Customer for test@example.com",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
<InvoiceItem invoiceitem id=ii_17WqA82eZvKYlo2CSYkrXgRX at 0x00000a> JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 1500,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Customer for test@example.com",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
Stripe\InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 1500,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Customer for test@example.com",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
com.stripe.model.InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 1500,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Customer for test@example.com",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
{
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 1500,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Customer for test@example.com",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}
&stripe.InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 1500,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Customer for test@example.com",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}

Delete 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

  • invoiceitem 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. Otherwise, this call returnsraisesraisesthrowsthrowsthrowsreturns an error, such as if 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});
invoiceitems.Del({INVOICEITEM_ID})
 
curl https://api.stripe.com/v1/invoiceitems/ii_17WqA82eZvKYlo2CSYkrXgRX \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ii = Stripe::InvoiceItem.retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX")
ii.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ii = stripe.InvoiceItem.retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX")
ii.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ii = \Stripe\InvoiceItem::retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX");
$ii->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

InvoiceItem ii = InvoiceItem.retrieve("ii_17WqA82eZvKYlo2CSYkrXgRX");
ii.delete();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoiceItems.del("ii_17WqA82eZvKYlo2CSYkrXgRX", function(err, confirmation) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := invoiceitem.Del("ii_17WqA82eZvKYlo2CSYkrXgRX")
 
{
  "deleted": true,
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX"
}
#<Stripe::Object id=ii_17WqA82eZvKYlo2CSYkrXgRX 0x00000a> JSON: {
  "deleted": true,
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX"
}
<Object object id=ii_17WqA82eZvKYlo2CSYkrXgRX at 0x00000a> JSON: {
  "deleted": true,
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX"
}
{
  "deleted": true,
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX"
}
nil

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 dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • 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 arrayMapobjectmap 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 returnraiseraisethrowthrowthrowreturn an 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/invoiceitems
Stripe::InvoiceItem.all
stripe.InvoiceItem.all()
\Stripe\InvoiceItem::all();
InvoiceItem.all(Map<String, Object> options);
stripe.invoiceItems.list();
invoiceitem.List()
 
curl https://api.stripe.com/v1/invoiceitems?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::InvoiceItem.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.InvoiceItem.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\InvoiceItem::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> invoiceItemParams = new HashMap<String, Object>();
invoiceItemParams.put("limit", 3);

Invoiceitem.all(invoiceItemParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoiceItems.list(
  { limit: 3 },
  function(err, invoiceitems) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.InvoiceItemListParams{}
params.Filters.AddFilter("limit", "", "3")
i := invoiceitem.List(params)
for i.Next() {
  i := i.InvoiceItem()
}
 
{
  "object": "list",
  "url": "/v1/invoiceitems",
  "has_more": false,
  "data": [
    {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "invoiceitem",
      "amount": 0,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1453650744,
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1454255541
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/invoiceitems",
  "has_more": false,
  "data": [
    #<Stripe::InvoiceItem id=ii_17WqA82eZvKYlo2CSYkrXgRX 0x00000a> JSON: {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "invoiceitem",
      "amount": 0,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1453650744,
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1454255541
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8"
    },
    #<Stripe::InvoiceItem[...] ...>,
    #<Stripe::InvoiceItem[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/invoiceitems",
  has_more: false,
  data: [
    <InvoiceItem invoiceitem id=ii_17WqA82eZvKYlo2CSYkrXgRX at 0x00000a> JSON: {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "invoiceitem",
      "amount": 0,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1453650744,
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1454255541
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8"
    },
    <stripe.InvoiceItem[...] ...>,
    <stripe.InvoiceItem[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/invoiceitems",
  "has_more" => false,
  "data" => [
    [0] => Stripe\InvoiceItem JSON: {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "invoiceitem",
      "amount": 0,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1453650744,
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1454255541
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8"
    }
    [1] => <Stripe\InvoiceItem[...] ...>
    [2] => <Stripe\InvoiceItem[...] ...>
  ]
}
#<com.stripe.model.InvoiceItemCollection id=#> JSON: {
  "data": [
    com.stripe.model.InvoiceItem JSON: {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "invoiceitem",
      "amount": 0,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1453650744,
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1454255541
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8"
    },
    #<com.stripe.model.InvoiceItem[...] ...>,
    #<com.stripe.model.InvoiceItem[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/invoiceitems",
  "has_more": false,
  "data": [
    {
      "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
      "object": "invoiceitem",
      "amount": 0,
      "currency": "usd",
      "customer": "cus_7oGjJvWit3N9Ps",
      "date": 1453650744,
      "description": "Unused time on Foo after 24 Jan 2016",
      "discountable": false,
      "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
      "livemode": false,
      "metadata": {
      },
      "period": {
        "start": 1453650744,
        "end": 1454255541
      },
      "plan": {
        "id": "25439foo1453650728",
        "object": "plan",
        "amount": 100,
        "created": 1453650733,
        "currency": "usd",
        "interval": "week",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Foo",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "proration": true,
      "quantity": 1,
      "subscription": "sub_7mOyPHYn697do8"
    },
    {...},
    {...}
  ]
}
&stripe.InvoiceItem JSON: {
  "id": "ii_17WqA82eZvKYlo2CSYkrXgRX",
  "object": "invoiceitem",
  "amount": 0,
  "currency": "usd",
  "customer": "cus_7oGjJvWit3N9Ps",
  "date": 1453650744,
  "description": "Unused time on Foo after 24 Jan 2016",
  "discountable": false,
  "invoice": "in_17WqA92eZvKYlo2CMvndrDo6",
  "livemode": false,
  "metadata": {
  },
  "period": {
    "start": 1453650744,
    "end": 1454255541
  },
  "plan": {
    "id": "25439foo1453650728",
    "object": "plan",
    "amount": 100,
    "created": 1453650733,
    "currency": "usd",
    "interval": "week",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Foo",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "proration": true,
  "quantity": 1,
  "subscription": "sub_7mOyPHYn697do8"
}

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"

  • 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 day, 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.

  • livemode boolean

  • metadata #

    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.

  • name string

    Display name of the plan

  • statement_descriptor string

    Extra information about a charge for the customer’s credit card statement.

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

{
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
#<Stripe::Plan id=gold2132 0x00000a> JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
<Plan plan id=gold2132 at 0x00000a> JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
Stripe\Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
com.stripe.model.Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
{
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
&stripe.Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}

Create a plan

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 day, week, month or year.

  • name required

    Name of the plan, to be displayed on invoices and in the web interface.

  • 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).

  • metadata optional

    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. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • statement_descriptor optional

    An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you’re charging for is your Silver Plan, you may want to specify a statement_descriptor of RunClub Silver Plan. The statement description may not include <>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all.

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

Returns

Returns the plan object.

POST https://api.stripe.com/v1/plans
Stripe::Plan.create
stripe.Plan.create()
\Stripe\Plan::create();
Plan.create();
stripe.plans.create();
plan.New()
 
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=gold

require "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")
\Stripe\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
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p, err := plan.New(&stripe.PlanParams{
  Amount: 2000,
  Interval: "month",
  Name: "Amazing Gold Plan",
  Currency: "usd",
  ID: "Gold",
})
 
{
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
#<Stripe::Plan id=gold2132 0x00000a> JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
<Plan plan id=gold2132 at 0x00000a> JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
Stripe\Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
com.stripe.model.Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
{
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
&stripe.Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}

Retrieve a plan

Retrieves the plan with the given ID.

Arguments

  • plan required

    The ID of the desired plan.

Returns

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

curl https://api.stripe.com/v1/plans/gold2132 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Plan.retrieve("gold2132")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Plan.retrieve("gold2132")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Plan::retrieve("gold2132");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Plan.retrieve("gold2132");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.plans.retrieve(
  "gold2132",
  function(err, plan) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p, err := plan.Get("gold2132", nil)
 
{
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
#<Stripe::Plan id=gold2132 0x00000a> JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
<Plan plan id=gold2132 at 0x00000a> JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
Stripe\Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
com.stripe.model.Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
{
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}
&stripe.Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": null
}

Update a plan

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

Arguments

  • plan required

    The identifier of the plan to be updated.

  • metadata optional

    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. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnullnull and then saving.

  • name optional

    Name of the plan, to be displayed on invoices and in the web interface.

  • statement_descriptor optional

    An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you’re charging for is your Silver Plan, you may want to specify a statement_descriptor of RunClub Silver Plan. The statement description may not include <>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. 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 nullnilNonenullnullnullnull and then saving.

Returns

The updated plan object is returned upon success. Otherwise, this call returnsraisesraisesthrowsthrowsthrowsreturns 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}
});
plan.Update({PLAN_ID}, &stripe.PlanParams{Name: {NAME}})
 
curl https://api.stripe.com/v1/plans/gold2132 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="New plan name"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p = Stripe::Plan.retrieve("gold2132")
p.name = "New plan name"
p.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p = stripe.Plan.retrieve("gold2132")
p.name = "New plan name"
p.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$p = \Stripe\Plan::retrieve("gold2132");
$p->name = "New plan name";
$p->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Plan p = Plan.retrieve("gold2132");
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("gold2132", {
  name: "New plan name"
}, function(err, plan) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p, err := plan.Update(
      "gold2132",
      &stripe.PlanParams{Name: "New plan name"},
    )
 
{
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "New plan name",
  "statement_descriptor": null,
  "trial_period_days": null
}
#<Stripe::Plan id=gold2132 0x00000a> JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "New plan name",
  "statement_descriptor": null,
  "trial_period_days": null
}
<Plan plan id=gold2132 at 0x00000a> JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "New plan name",
  "statement_descriptor": null,
  "trial_period_days": null
}
Stripe\Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "New plan name",
  "statement_descriptor": null,
  "trial_period_days": null
}
com.stripe.model.Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "New plan name",
  "statement_descriptor": null,
  "trial_period_days": null
}
{
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "New plan name",
  "statement_descriptor": null,
  "trial_period_days": null
}
&stripe.Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "New plan name",
  "statement_descriptor": null,
  "trial_period_days": null
}

Delete 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

  • plan 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 returnsraisesraisesthrowsthrowsthrowsreturns 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});
plan.Del({PLAN_ID})
 
curl https://api.stripe.com/v1/plans/gold2132 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

plan = Stripe::Plan.retrieve("gold2132")
plan.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

plan = stripe.Plan.retrieve("gold2132")
plan.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$plan = \Stripe\Plan::retrieve("gold2132");
$plan->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Plan plan = Plan.retrieve("gold2132");
plan.delete();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.plans.del(
  "gold2132",
  function(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := plan.Del("gold2132")
 
{
  "deleted": true,
  "id": "gold2132"
}
#<Stripe::Object id=gold2132 0x00000a> JSON: {
  "deleted": true,
  "id": "gold2132"
}
<Object object id=gold2132 at 0x00000a> JSON: {
  "deleted": true,
  "id": "gold2132"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "gold2132"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "gold2132"
}
{
  "deleted": true,
  "id": "gold2132"
}
nil

List all plans

Returns a list of your plans.

Arguments

  • created optional dictionaryhashdictionaryassociative arrayMapobjectmap

    A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    child arguments

    • gt optional

      Return values where the created field is after this timestamp.

    • gte optional

      Return values where the created field is after or equal to this timestamp.

    • lt optional

      Return values where the created field is before this timestamp.

    • lte optional

      Return values where the created field is before or equal to this timestamp.

  • 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 arrayMapobjectmap 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 returnraiseraisethrowthrowthrowreturn an an error.

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

GET https://api.stripe.com/v1/plans
Stripe::Plan.all
stripe.Plan.all()
\Stripe\Plan::all();
Plan.all(Map<String, Object> options);
stripe.plans.list();
plan.List()
 
curl https://api.stripe.com/v1/plans?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Plan.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Plan.all(limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Plan::all(array("limit" => 3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> planParams = new HashMap<String, Object>();
planParams.put("limit", 3);

Plan.all(planParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.plans.list(
  { limit: 3 },
  function(err, plans) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.PlanListParams{}
params.Filters.AddFilter("limit", "", "3")
i := plan.List(params)
for i.Next() {
  p := i.Plan()
}
 
{
  "object": "list",
  "url": "/v1/plans",
  "has_more": false,
  "data": [
    {
      "id": "gold2132",
      "object": "plan",
      "amount": 2000,
      "created": 1386249594,
      "currency": "usd",
      "interval": "month",
      "interval_count": 1,
      "livemode": false,
      "metadata": {
      },
      "name": "Gold ",
      "statement_descriptor": null,
      "trial_period_days": null
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/plans",
  "has_more": false,
  "data": [
    #<Stripe::Plan id=gold2132 0x00000a> JSON: {
      "id": "gold2132",
      "object": "plan",
      "amount": 2000,
      "created": 1386249594,
      "currency": "usd",
      "interval": "month",
      "interval_count": 1,
      "livemode": false,
      "metadata": {
      },
      "name": "Gold ",
      "statement_descriptor": null,
      "trial_period_days": null
    },
    #<Stripe::Plan[...] ...>,
    #<Stripe::Plan[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/plans",
  has_more: false,
  data: [
    <Plan plan id=gold2132 at 0x00000a> JSON: {
      "id": "gold2132",
      "object": "plan",
      "amount": 2000,
      "created": 1386249594,
      "currency": "usd",
      "interval": "month",
      "interval_count": 1,
      "livemode": false,
      "metadata": {
      },
      "name": "Gold ",
      "statement_descriptor": null,
      "trial_period_days": null
    },
    <stripe.Plan[...] ...>,
    <stripe.Plan[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/plans",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Plan JSON: {
      "id": "gold2132",
      "object": "plan",
      "amount": 2000,
      "created": 1386249594,
      "currency": "usd",
      "interval": "month",
      "interval_count": 1,
      "livemode": false,
      "metadata": {
      },
      "name": "Gold ",
      "statement_descriptor": null,
      "trial_period_days": null
    }
    [1] => <Stripe\Plan[...] ...>
    [2] => <Stripe\Plan[...] ...>
  ]
}
#<com.stripe.model.PlanCollection id=#> JSON: {
  "data": [
    com.stripe.model.Plan JSON: {
      "id": "gold2132",
      "object": "plan",
      "amount": 2000,
      "created": 1386249594,
      "currency": "usd",
      "interval": "month",
      "interval_count": 1,
      "livemode": false,
      "metadata": {
      },
      "name": "Gold ",
      "statement_descriptor": null,
      "trial_period_days": null
    },
    #<com.stripe.model.Plan[...] ...>,
    #<com.stripe.model.Plan[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/plans",
  "has_more": false,
  "data": [
    {
      "id": "gold2132",
      "object": "plan",
      "amount": 2000,
      "created": 1386249594,
      "currency": "usd",
      "interval": "month",
      "interval_count": 1,
      "livemode": false,
      "metadata": {
      },
      "name": "Gold ",
      "statement_descriptor": null,
      "trial_period_days": null
    },
    {...},
    {...}
  ]
}
&stripe.Plan JSON: {
  "id": "gold2132",
  "object": "plan",
  "amount": 2000,
  "created": 1386249594,
  "currency": "usd",
  "interval": "month",
  "interval_count": 1,
  "livemode": false,
  "metadata": {
  },
  "name": "Gold ",
  "statement_descriptor": null,
  "trial_period_days": 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.

Updating a subscription by changing the plan or quantity generates a new Subscription object.

The subscription object

Attributes

  • id string

  • object string , value is "subscription"

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

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

  • 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

  • customer string

  • 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

  • metadata #

    A set of key/value pairs that you can attach to a subscription object. It can be useful for storing additional information about the subscription in a structured format.

  • 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. Additionally, updating customer card details will not lead to Stripe retrying the latest invoice.). After receiving updated card details from a customer, you may choose to reopen and pay their closed invoices.

  • tax_percent decimal

    If provided, each invoice created by this subscription will apply the tax rate, increasing the amount billed to the customer.

  • 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_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
#<Stripe::StripeObject id=sub_7oH6r1H2fws6yk 0x00000a> JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
<StripeObject subscription id=sub_7oH6r1H2fws6yk at 0x00000a> JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
Stripe\StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
com.stripe.model.StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
{
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
&stripe.StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}

Create a subscription

Creates a new subscription on an existing customer.

Arguments

  • application_fee_percent optional, default is nullnilNonenullnullnullnull

    A positive decimal (with at most two decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal 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.

  • coupon optional, default is nullnilNonenullnullnullnull

    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.

  • plan required

    The identifier of the plan to subscribe the customer to.

  • source optional, default is nullnilNonenullnullnullnull

    The source can either be a token, like the ones returned by our Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's credit card details (with the options shown below). You must provide a source if the customer does not already have a valid source attached, and you are subscribing the customer for a plan that is not free. Passing source will create a new source object, make it the customer default source, and delete the old customer default if one exists. If you want to add an additional source 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.

    child parameters

    • exp_monthexp_monthexp_monthexp_monthexp_monthexp_monthexp_month required

      Two digit number representing the card's expiration month.

    • exp_yearexp_yearexp_yearexp_yearexp_yearexp_yearexp_year required

      Two or four digit number representing the card's expiration year.

    • objectobjectobjectobjectobjectobjectobject required

      The type of payment source. Should be "card".

    • numbernumbernumbernumbernumbernumbernumber required

      The card number, as a string without any separators.

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

    • cvccvccvccvccvccvccvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • namenamenamenamenamenamename optional

      Cardholder's full name.

  • quantity optional, default is 1111111

    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.

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a subscription object. It can be useful for storing additional information about the subscription in a structured format.

  • tax_percent optional, default is nullnilNonenullnullnullnull

    A positive decimal (with at most two decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice.

  • trial_end optional, default is nullnilNonenullnullnullnull

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

Returns

The newly created subscription object if the call succeeded.

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

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions
customer = 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<String, Object> params = new HashMap<String, Object>();
params.put("plan", {PLAN_ID});
cu.createSubscription(params);
stripe.customers.createSubscription({CUSTOMER_ID}, {
  plan: {PLAN_ID}
});
sub.New(&stripe.SubParams{Customer: {CUSTOMER_ID}, Plan: {PLAN_ID}})
 
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d plan=gold2132

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
customer.subscriptions.create(:plan => "gold2132")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
customer.subscriptions.create(plan="gold2132")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$cu->subscriptions->create(array("plan" => "gold2132"));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
Map<String, Object> params = new HashMap<String, Object>();
params.put("plan", "gold2132");
cu.createSubscription(params)
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.createSubscription(
  "cus_7oGjJvWit3N9Ps",
  {plan: "gold2132"},
  function(err, subscription) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

s, err := sub.New(&stripe.SubParams{
  Customer: "cus_7oGjJvWit3N9Ps",
  Plan: "gold2132",
})
 
{
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
#<Stripe::StripeObject id=sub_7oH6r1H2fws6yk 0x00000a> JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
<StripeObject subscription id=sub_7oH6r1H2fws6yk at 0x00000a> JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
Stripe\StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
com.stripe.model.StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
{
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
&stripe.StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}

Retrieve a 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

  • customer required

  • id required

    ID of subscription to retrieve.

Returns

Returns the subscription object. 

curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions/sub_7oH6r1H2fws6yk \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
subscription = customer.subscriptions.retrieve("sub_7oH6r1H2fws6yk")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
subscription = customer.subscriptions.retrieve("sub_7oH6r1H2fws6yk")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$customer = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$subscription = $customer->subscriptions->retrieve("sub_7oH6r1H2fws6yk");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
Subscription subscription = cu.getSubscriptions().retrieve("sub_7oH6r1H2fws6yk");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.retrieveSubscription(
  "cus_7oGjJvWit3N9Ps",
  "sub_7oH6r1H2fws6yk",
  function(err, subscription) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

s, err := sub.Get(
  "sub_7oH6r1H2fws6yk",
  &stripe.SubParams{Customer: "cus_7oGjJvWit3N9Ps"},
)
 
{
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
#<Stripe::StripeObject id=sub_7oH6r1H2fws6yk 0x00000a> JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
<StripeObject subscription id=sub_7oH6r1H2fws6yk at 0x00000a> JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
Stripe\StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
com.stripe.model.StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
{
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
&stripe.StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}

Update 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. To preview how the proration will be calculated, use the upcoming invoice endpoint.

Arguments

  • application_fee_percent optional, default is nullnilNonenullnullnullnull

    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.

  • coupon optional, default is nullnilNonenullnullnullnull

    The code of the coupon to apply to the customer if you would like to apply it at the same time as updating the subscription.

  • plan optional

    The identifier of the plan to update the subscription to. If omitted, the subscription will not change plans.

  • prorate optional, default is true

    Flag telling us whether to prorate switching plans during a billing cycle.

  • proration_date optional, default is the current time

    If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same proration that was previewed with upcoming invoice endpoint. It can also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations.

  • metadata optional, default is { }{ }{ }{ }{ }{ }{ }

    A set of key/value pairs that you can attach to a subscription object. It can be useful for storing additional information about the subscription in a structured format.

  • quantity optional, default is 1111111

    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.

  • source optional, default is nullnilNonenullnullnullnull

    The source can either be a token, like the ones returned by our Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobjectmap containing a user's credit card details (with the options shown below). You must provide a source if the customer does not already have a valid source attached, and you are subscribing the customer for a plan that is not free. Passing source will create a new source object, make it the customer default source, and delete the old customer default if one exists. If you want to add an additional source 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.

    child parameters

    • objectobjectobjectobjectobjectobjectobject required

      The type of payment source. Should be "card".

    • exp_monthexp_monthexp_monthexp_monthexp_monthexp_monthexp_month required

      Two digit number representing the card's expiration month.

    • exp_yearexp_yearexp_yearexp_yearexp_yearexp_yearexp_year required

      Two or four digit number representing the card's expiration year.

    • numbernumbernumbernumbernumbernumbernumber required

      The card number, as a string without any separators.

    • cvccvccvccvccvccvccvc usually required

      Card security code. Required unless your account is registered in Australia, Canada, or the United States. Highly recommended to always include this value.

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

    • namenamenamenamenamenamename optional

      Cardholder's full name.

  • tax_percent optional, default is nullnilNonenullnullnullnull

    Update the amount of tax applied to this subscription. Changing the tax_percent of a subscription will only affect future invoices.

  • trial_end optional, default is nullnilNonenullnullnullnull

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

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. (Note that if we charge for the new plan, and that payment fails, the plan change will not go into effect).

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 falsefalsefalsefalsefalsefalsefalse 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 updated subscription object if the call succeeded.

If a charge is required for the update, and the charge fails, this call returnsraisesraisesthrowsthrowsthrowsreturns an error, and the subscription update does not go into effect. 

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.getSubscriptions().retrieve({SUBSCRIPTION_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("plan", {PLAN_ID});
subscription.update(updateParams);
stripe.customers.updateSubscription({CUSTOMER_ID}, {SUBSCRIPTION_ID}, {
  plan: {PLAN_ID}
})
sub.Update({SUBSCRIPTION_ID}, &stripe.SubParams{Customer: {CUSTOMER_ID}, Plan: {PLAN_ID}})
 
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions/sub_7oH6r1H2fws6yk \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d plan=gold2132

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
subscription = customer.subscriptions.retrieve("sub_7oH6r1H2fws6yk")
subscription.plan = "gold2132"
subscription.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
subscription = customer.subscriptions.retrieve("sub_7oH6r1H2fws6yk")
subscription.plan = "gold2132"
subscription.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$subscription = $cu->subscriptions->retrieve("sub_7oH6r1H2fws6yk");
$subscription->plan = "gold2132";
$subscription->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
Subscription subscription = cu.getSubscriptions().retrieve("sub_7oH6r1H2fws6yk");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("plan", "gold2132");
subscription.update(updateParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.updateSubscription(
  "cus_7oGjJvWit3N9Ps",
  "sub_7oH6r1H2fws6yk",
  { plan: "gold2132" },
  function(err, subscription) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

s, err := sub.Update(
      "sub_7oH6r1H2fws6yk",
      &stripe.SubParams{
        Customer: "cus_7oGjJvWit3N9Ps",
        Plan: "gold2132",
      },
    )
 
{
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
#<Stripe::StripeObject id=sub_7oH6r1H2fws6yk 0x00000a> JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
<StripeObject subscription id=sub_7oH6r1H2fws6yk at 0x00000a> JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
Stripe\StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
com.stripe.model.StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
{
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
&stripe.StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}

Cancel a 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})
sub.Cancel({SUBSCRIPTION_ID}, &stripe.SubParams{Customer: {CUSTOMER_ID})
 
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions/sub_7oH6r1H2fws6yk \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps")
customer.subscriptions.retrieve("sub_7oH6r1H2fws6yk").delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps")
customer.subscriptions.retrieve("sub_7oH6r1H2fws6yk").delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps");
$cu->subscriptions->retrieve("sub_7oH6r1H2fws6yk")->cancel();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
for(Subscription subscription : cu.getSubscriptions().getData()){
  if(subscription.getId().equals("sub_7oH6r1H2fws6yk")){
    subscription.cancel(null);
    break;
  }
}
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.cancelSubscription(
  "cus_7oGjJvWit3N9Ps",
  "sub_7oH6r1H2fws6yk",
  function(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := sub.Cancel(
  "sub_7oH6r1H2fws6yk",
  &stripe.SubParams{Customer: "cus_7oGjJvWit3N9Ps"},
)
 
{
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "canceled",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
#<Stripe::StripeObject id=sub_7oH6r1H2fws6yk 0x00000a> JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "canceled",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
<StripeObject subscription id=sub_7oH6r1H2fws6yk at 0x00000a> JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "canceled",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
Stripe\StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "canceled",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
com.stripe.model.Deletedsubscription JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "deletedsubscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "canceled",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
{
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "canceled",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}
nil

List active 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

  • customer 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}/subscriptions
Stripe::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});
sub.List()
 
curl https://api.stripe.com/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.retrieve("cus_7oGjJvWit3N9Ps").subscriptions.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.retrieve("cus_7oGjJvWit3N9Ps").subscriptions.all(
  limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::retrieve("cus_7oGjJvWit3N9Ps")->subscriptions->all(array(
  'limit'=>3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_7oGjJvWit3N9Ps");
Map<String, Object> subscriptionParams = new HashMap<String, Object>();
subscriptionParams.put("limit", 3);
CustomerSubscriptionCollection subscriptions = cu.getSubscriptions().all(subscriptionParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.listSubscriptions('cus_7oGjJvWit3N9Ps', function(err, subscriptions) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.SubListParams{Customer: "cus_7oGjJvWit3N9Ps"}
params.Filters.AddFilter("limit", "", "3")
i := sub.List(params)
for i.Next() {
  s := i.Sub()
}
 
{
  "object": "list",
  "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions",
  "has_more": false,
  "data": [
    {
      "id": "sub_7oH6r1H2fws6yk",
      "object": "subscription",
      "application_fee_percent": null,
      "cancel_at_period_end": false,
      "canceled_at": null,
      "current_period_end": 1456761177,
      "current_period_start": 1454082777,
      "customer": "cus_7oGjJvWit3N9Ps",
      "discount": null,
      "ended_at": null,
      "metadata": {
      },
      "plan": {
        "id": "gold2132",
        "object": "plan",
        "amount": 2000,
        "created": 1386249594,
        "currency": "usd",
        "interval": "month",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Gold ",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "quantity": 1,
      "start": 1454082777,
      "status": "active",
      "tax_percent": null,
      "trial_end": null,
      "trial_start": null
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions",
  "has_more": false,
  "data": [
    #<Stripe::StripeObject id=sub_7oH6r1H2fws6yk 0x00000a> JSON: {
      "id": "sub_7oH6r1H2fws6yk",
      "object": "subscription",
      "application_fee_percent": null,
      "cancel_at_period_end": false,
      "canceled_at": null,
      "current_period_end": 1456761177,
      "current_period_start": 1454082777,
      "customer": "cus_7oGjJvWit3N9Ps",
      "discount": null,
      "ended_at": null,
      "metadata": {
      },
      "plan": {
        "id": "gold2132",
        "object": "plan",
        "amount": 2000,
        "created": 1386249594,
        "currency": "usd",
        "interval": "month",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Gold ",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "quantity": 1,
      "start": 1454082777,
      "status": "active",
      "tax_percent": null,
      "trial_end": null,
      "trial_start": null
    },
    #<Stripe::Subscription[...] ...>,
    #<Stripe::Subscription[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions",
  has_more: false,
  data: [
    <StripeObject subscription id=sub_7oH6r1H2fws6yk at 0x00000a> JSON: {
      "id": "sub_7oH6r1H2fws6yk",
      "object": "subscription",
      "application_fee_percent": null,
      "cancel_at_period_end": false,
      "canceled_at": null,
      "current_period_end": 1456761177,
      "current_period_start": 1454082777,
      "customer": "cus_7oGjJvWit3N9Ps",
      "discount": null,
      "ended_at": null,
      "metadata": {
      },
      "plan": {
        "id": "gold2132",
        "object": "plan",
        "amount": 2000,
        "created": 1386249594,
        "currency": "usd",
        "interval": "month",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Gold ",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "quantity": 1,
      "start": 1454082777,
      "status": "active",
      "tax_percent": null,
      "trial_end": null,
      "trial_start": null
    },
    <stripe.Subscription[...] ...>,
    <stripe.Subscription[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions",
  "has_more" => false,
  "data" => [
    [0] => Stripe\StripeObject JSON: {
      "id": "sub_7oH6r1H2fws6yk",
      "object": "subscription",
      "application_fee_percent": null,
      "cancel_at_period_end": false,
      "canceled_at": null,
      "current_period_end": 1456761177,
      "current_period_start": 1454082777,
      "customer": "cus_7oGjJvWit3N9Ps",
      "discount": null,
      "ended_at": null,
      "metadata": {
      },
      "plan": {
        "id": "gold2132",
        "object": "plan",
        "amount": 2000,
        "created": 1386249594,
        "currency": "usd",
        "interval": "month",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Gold ",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "quantity": 1,
      "start": 1454082777,
      "status": "active",
      "tax_percent": null,
      "trial_end": null,
      "trial_start": null
    }
    [1] => <Stripe\Subscription[...] ...>
    [2] => <Stripe\Subscription[...] ...>
  ]
}
#<com.stripe.model.SubscriptionCollection id=#> JSON: {
  "data": [
    com.stripe.model.StripeObject JSON: {
      "id": "sub_7oH6r1H2fws6yk",
      "object": "subscription",
      "application_fee_percent": null,
      "cancel_at_period_end": false,
      "canceled_at": null,
      "current_period_end": 1456761177,
      "current_period_start": 1454082777,
      "customer": "cus_7oGjJvWit3N9Ps",
      "discount": null,
      "ended_at": null,
      "metadata": {
      },
      "plan": {
        "id": "gold2132",
        "object": "plan",
        "amount": 2000,
        "created": 1386249594,
        "currency": "usd",
        "interval": "month",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Gold ",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "quantity": 1,
      "start": 1454082777,
      "status": "active",
      "tax_percent": null,
      "trial_end": null,
      "trial_start": null
    },
    #<com.stripe.model.Subscription[...] ...>,
    #<com.stripe.model.Subscription[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers/cus_7oGjJvWit3N9Ps/subscriptions",
  "has_more": false,
  "data": [
    {
      "id": "sub_7oH6r1H2fws6yk",
      "object": "subscription",
      "application_fee_percent": null,
      "cancel_at_period_end": false,
      "canceled_at": null,
      "current_period_end": 1456761177,
      "current_period_start": 1454082777,
      "customer": "cus_7oGjJvWit3N9Ps",
      "discount": null,
      "ended_at": null,
      "metadata": {
      },
      "plan": {
        "id": "gold2132",
        "object": "plan",
        "amount": 2000,
        "created": 1386249594,
        "currency": "usd",
        "interval": "month",
        "interval_count": 1,
        "livemode": false,
        "metadata": {
        },
        "name": "Gold ",
        "statement_descriptor": null,
        "trial_period_days": null
      },
      "quantity": 1,
      "start": 1454082777,
      "status": "active",
      "tax_percent": null,
      "trial_end": null,
      "trial_start": null
    },
    {...},
    {...}
  ]
}
&stripe.StripeObject JSON: {
  "id": "sub_7oH6r1H2fws6yk",
  "object": "subscription",
  "application_fee_percent": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "current_period_end": 1456761177,
  "current_period_start": 1454082777,
  "customer": "cus_7oGjJvWit3N9Ps",
  "discount": null,
  "ended_at": null,
  "metadata": {
  },
  "plan": {
    "id": "gold2132",
    "object": "plan",
    "amount": 2000,
    "created": 1386249594,
    "currency": "usd",
    "interval": "month",
    "interval_count": 1,
    "livemode": false,
    "metadata": {
    },
    "name": "Gold ",
    "statement_descriptor": null,
    "trial_period_days": null
  },
  "quantity": 1,
  "start": 1454082777,
  "status": "active",
  "tax_percent": null,
  "trial_end": null,
  "trial_start": null
}