API Reference

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

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

Libraries

Libraries are available in several languages.

https://api.stripe.com

Authentication

You authenticate to the Stripe API by providing your secret API key in the request. You can manage your API keys from your account. Your API keys carry many privileges, so be sure to keep them secret!

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

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

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

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

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

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

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

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

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
\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 will prevent it from asking you for a password). You can set a default key, or you can always pass a key directly to an object's constructor. Authentication is transparently handled for you in subsequent method calls. You can set a key by passing it to the Stripe module (a constructor). Authentication is transparently handled for you in subsequent method calls.

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

Errors

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

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

Attributes
  • type

    The type of error returned. Can be invalid_request_error, api_error, or card_error.

  • message optional

    A human-readable message giving more details about the error. For card errors, these messages can be shown to your users.

  • code optional

    For card errors, a short string from amongst those listed on the right describing the kind of card error that occurred.

  • param optional

    The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.

HTTP Status Code Summary

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

Errors

Types
invalid_request_error Invalid request errors arise when your request has invalid parameters.
api_error API errors cover any other type of problem (e.g. a temporary problem with Stripe's servers) and should turn up only very infrequently.
card_error Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason.
Codes
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.
rate_limit An error occurred due to requests hitting the API too quickly. Please let us know if you're consistently running into this error.
CVC validation and zip validation can be enabled/disabled in your settings.

Handling errors

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

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

begin
  # Use Stripe's bindings...
rescue Stripe::CardError => e
  # Since it's a decline, Stripe::CardError will be caught
  body = e.json_body
  err  = body[:error]

  puts "Status is: #{e.http_status}"
  puts "Type is: #{err[:type]}"
  puts "Code is: #{err[:code]}"
  # param is '' in this case
  puts "Param is: #{err[:param]}"
  puts "Message is: #{err[:message]}"
rescue Stripe::InvalidRequestError => e
  # Invalid parameters were supplied to Stripe's API
rescue Stripe::AuthenticationError => e
  # Authentication with Stripe's API failed
  # (maybe you changed API keys recently)
rescue Stripe::APIConnectionError => e
  # Network communication with Stripe failed
rescue Stripe::StripeError => e
  # Display a very generic error to the user, and maybe send
  # yourself an email
rescue => e
  # Something else happened, completely unrelated to Stripe
end
try:
  # Use Stripe's bindings...
  pass
except stripe.error.CardError, e:
  # Since it's a decline, stripe.error.CardError will be caught
  body = e.json_body
  err  = body['error']

  print "Status is: %s" % e.http_status
  print "Type is: %s" % err['type']
  print "Code is: %s" % err['code']
  # param is '' in this case
  print "Param is: %s" % err['param']
  print "Message is: %s" % err['message']
except stripe.error.InvalidRequestError, e:
  # Invalid parameters were supplied to Stripe's API
  pass
except stripe.error.AuthenticationError, e:
  # Authentication with Stripe's API failed
  # (maybe you changed API keys recently)
  pass
except stripe.error.APIConnectionError, e:
  # Network communication with Stripe failed
  pass
except stripe.error.StripeError, e:
  # Display a very generic error to the user, and maybe send
  # yourself an email
  pass
except Exception, e:
  # Something else happened, completely unrelated to Stripe
  pass
try {
  // Use Stripe's bindings...
} 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\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 bindings...
} catch (CardException e) {
  // Since it's a decline, CardException will be caught
  System.out.println("Status is: " + e.getCode());
  System.out.println("Message is: " + e.getMessage());
} catch (InvalidRequestException e) {
  // Invalid parameters were supplied to Stripe's API
} catch (AuthenticationException e) {
  // Authentication with Stripe's API failed
  // (maybe you changed API keys recently)
} catch (APIConnectionException e) {
  // Network communication with Stripe failed
} catch (StripeException e) {
  // Display a very generic error to the user, and maybe send
  // yourself an email
} catch (Exception e) {
  // Something else happened, completely unrelated to Stripe
}
// Note: Node.js API does not throw exceptions (except in
// the case of missing arguments)
//
// An error from the Stripe API or an otheriwse asynchronous error
// will be available as the first argument of any Stripe method's callback:
// E.g. stripe.customers.create({...}, function(err, result) {});
//
// Or in the form of a rejected promise.
// E.g. stripe.customers.create({...}).then(
//        function(result) {},
//        function(err) {}
//      );

switch (err.type) {
  case 'StripeCardError':
    // A declined card error
    err.message; // => e.g. "Your card's expiration year is invalid."
    break;
  case 'StripeInvalidRequest':
    // 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;
}
_, err := // Go bindings 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:
  case stripe.RateLimit:
  }
}

Pagination

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

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

Arguments
  • limit optional

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

List Response Format
  • object string, value is "list"

    A string describing the type of the object.

  • data array

    An array containing the actual response elements, paginated by any request parameters.

  • has_more boolean

    Whether or not there are more elements available after this page. If false, this page is the end of the list.

  • url string

    The URL where this list can be accessed.

curl https://api.stripe.com/v1/customers?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": [
    {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    #<Stripe::Customer id=cus_6iyQXxYdktOlra 0x00000a> JSON: {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    },
    #<Stripe::Customer[...] ...>,
    #<Stripe::Customer[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers",
  has_more: false,
  data: [
    <Customer customer id=cus_6iyQXxYdktOlra at 0x00000a> JSON: {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    },
    <stripe.Customer[...] ...>,
    <stripe.Customer[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Customer JSON: {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    }
    [1] => <Stripe\Customer[...] ...>
    [2] => <Stripe\Customer[...] ...>
  ]
}
#<com.stripe.model.CustomerCollection id=#> JSON: {
  "data": [
    com.stripe.model.Customer JSON: {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    },
    #<com.stripe.model.Customer[...] ...>,
    #<com.stripe.model.Customer[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    },
    {...},
    {...}
  ]
}
&stripe.Customer JSON: {
  "object": "customer",
  "created": 1438560411,
  "id": "cus_6iyQXxYdktOlra",
  "livemode": false,
  "description": "Customer",
  "email": "user1502@example.com",
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
    "data": [

    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
    "data": [
      {
        "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 8,
        "exp_year": 2019,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": null,
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_6iyQXxYdktOlra"
      }
    ]
  },
  "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
}

Versioning

When we make backwards-incompatible changes to the API, we release new dated versions. The current version is 2015-07-28. 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 by sending a Stripe-Version header identifying the API version to use. (For libraries and bindings, this is done by setting an API version property as in the code examples.) Note that events generated by API requests will always be structured according to your account API version, even when using the Stripe-Version header.

You can visit your dashboard to upgrade your API version.

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -H "Stripe-Version: 2015-07-28"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
Stripe.api_version = "2015-07-28"
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
stripe.api_version = '2015-07-28'
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
\Stripe\Stripe::setApiVersion("2015-07-28");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
Stripe.apiVersion = "2015-07-28";
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);
stripe.setApiVersion('2015-07-28');
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
// Since Go bindings are strongly typed,
// the version is fixed in the library.

Expanding Objects

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

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

curl https://api.stripe.com/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d expand[]=customer
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

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

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

Metadata

Most updatable Stripe objects (charges, coupons, customers, disputes, invoices, invoice items, plans, recipients, refunds, subscriptions, and transfers) support a user-specified metadata parameter.

You can use the metadata parameter to attach key-value data. This is useful for storing additional structured information about an object. As an example, you could store your user's full name, favorite color, and their corresponding unique identifier from your system on a Stripe customer object.

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

If you have Stripe email receipts enabled, the description on a charge or invoice item will appear on the email receipt that is sent to your customer.

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

Note: You can have up to 20 keys, with key names up to 40 characters long and values up to 500 characters long. However, we're very curious to hear about any cases where you'd like to use more than that – please email support@stripe.com.

Sample metadata use cases
  • Link IDs

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

  • Shipping information

    Store shipping status and tracking numbers on a charge to easily track the status of an order.

  • Product plan

    Annotate a customer, charge, recipient, or transfer with the product in use. For example, a charge may have been made under an 'enterprise' or 'personal' product.

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

Stripe::Charge.create(
  :amount => 400,
  :currency => "usd",
  :source => "tok_16V4wQ2eZvKYlo2CwPLkIJ82", # 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_16V4wQ2eZvKYlo2CwPLkIJ82", # obtained with Stripe.js
  metadata={'order_id': '6735'}
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::create(array(
  "amount" => 400,
  "currency" => "usd",
  "source" => "tok_16V4wQ2eZvKYlo2CwPLkIJ82", // 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_16V4wQ2eZvKYlo2CwPLkIJ82"); // 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_16V4wQ2eZvKYlo2CwPLkIJ82", // obtained with Stripe.js
  metadata: {'order_id': '6735'}
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ChargeParams{
  Amount: 400,
  Currency: "usd",
}
params.SetSource("tok_16V4wQ2eZvKYlo2CwPLkIJ82") // obtained with Stripe.js
params.AddMeta("order_id", "6735")
charge.New(params)
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
#<Stripe::Charge id=ch_16VYlI2eZvKYlo2CyajKjsYz 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
<Charge charge id=ch_16VYlI2eZvKYlo2CyajKjsYz at 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
Stripe\Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
com.stripe.model.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
&stripe.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}

Idempotent Requests

To safely retry an API request without accidentally performing the same operation twice, you can attach a unique key to any POST request made to the Stripe API via the Idempotency-Key: <key> header.

For example, if a request to create a charge fails due to a network connection error, you can make a second request with the same key to guarantee that only a single charge is created.

The creation of the key 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, even if you make the request with different request parameters. The keys expire after 24 hours.

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -H "Idempotency-Key: KOgE2yqd7FLl3vvI" \
   -d amount=400 \
   -d source=tok_16V4wQ2eZvKYlo2CwPLkIJ82 \
   -d currency=usd
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

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

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

stripe.charges.create({
  amount: 400,
  currency: "usd",
  source: "tok_16V4wQ2eZvKYlo2CwPLkIJ82", // obtained with Stripe.js
  description: "Charge for test@example.com"
}, {
  idempotency_key: "KOgE2yqd7FLl3vvI"
}, 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_16V4wQ2eZvKYlo2CwPLkIJ82") // obtained with Stripe.js
args.Params.IdempotencyKey = "KOgE2yqd7FLl3vvI"
ch, err := charge.New(args)

Request IDs

Each API request has an associated request identifier. You can find this in the response headers, under Request-Id. You can also find it in the URLs of individual request logs in your Stripe dashboard. If you need to contact us about a specific request, it can be helpful to have this ID handy.

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"

  • livemode boolean

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

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

  • metadata metadata hash

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

  • paid boolean

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

  • 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 reversed, in cents.

      • created timestamp

      • currency currency

        Three-letter ISO code representing the currency of the reversal.

      • metadata metadata hash

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

      • balance_transaction string

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

      • charge string

        ID of the charge that was refunded.

      • description string

      • 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

    • url string

      The URL where this list can be accessed.

    • 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

  • source hash

    For most Stripe users, the source of every charge is a credit or debit card. This hash is then the card object describing that card.

  • status string

    The status of the payment is either succeeded or failed.

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

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

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

  • shipping hash

    Shipping information for the charge.

    child attributes
    • address hash

      Shipping address.

      child attributes
      • line1 string

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

      • line2 string

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

      • city string

        City/Suburb/Town/Village

      • state string

        State/Province/County

      • postal_code string

        Zip/Postal Code

      • country string

        2-letter country code

    • name string

      Recipient name.

    • carrier string

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

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

  • transfer string

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

{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
#<Stripe::Charge id=ch_16VYlI2eZvKYlo2CyajKjsYz 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
<Charge charge id=ch_16VYlI2eZvKYlo2CyajKjsYz at 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
Stripe\Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
com.stripe.model.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
&stripe.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}

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.

  • 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
    • objectobjectobjectobjectobjectobjectobject required

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

    • numbernumbernumbernumbernumbernumbernumber required

      The 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 optional, highly recommended

      Card security code.

    • namenamenamenamenamenamename optional

      Cardholder's full name.

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

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

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

  • capture optional, default is true

    Whether or not to immediately capture the charge. When false, the charge issues an authorization (or pre-authorization), and will need to be captured later. Uncaptured charges expire in 7 days. For more information, see authorizing charges and settling later.

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

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

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

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

  • shipping optional, default is { }

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

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 similarly try to check the validity of those parameters. Some banks do not support checking one or more of these parameters, in which case Stripe will return an '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_16V4wQ2eZvKYlo2CwPLkIJ82 \
   -d description="Charge for test@example.com"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.create(
  :amount => 400,
  :currency => "usd",
  :source => "tok_16V4wQ2eZvKYlo2CwPLkIJ82", # 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_16V4wQ2eZvKYlo2CwPLkIJ82", # 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_16V4wQ2eZvKYlo2CwPLkIJ82", // 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_16V4wQ2eZvKYlo2CwPLkIJ82"); // 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_16V4wQ2eZvKYlo2CwPLkIJ82", // 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_16V4wQ2eZvKYlo2CwPLkIJ82")
ch, err := charge.New(chargeParams)
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
#<Stripe::Charge id=ch_16VYlI2eZvKYlo2CyajKjsYz 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
<Charge charge id=ch_16VYlI2eZvKYlo2CyajKjsYz at 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
Stripe\Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
com.stripe.model.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
&stripe.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}

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
  • id required

    The identifier of the charge to be retrieved.

Returns

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

curl https://api.stripe.com/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

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

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

c, err := charge.Get("ch_16VYlI2eZvKYlo2CyajKjsYz", nil)
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
#<Stripe::Charge id=ch_16VYlI2eZvKYlo2CyajKjsYz 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
<Charge charge id=ch_16VYlI2eZvKYlo2CyajKjsYz at 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
Stripe\Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
com.stripe.model.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
&stripe.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}

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_emailand fraud_details 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.

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

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

  • 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_16VYlI2eZvKYlo2CyajKjsYz \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Charge for test@example.com"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

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

ch, err := charge.Update(
  "ch_16VYlI2eZvKYlo2CyajKjsYz",
  &stripe.ChargeParams{Desc: "Charge for test@example.com"},
)
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
#<Stripe::Charge id=ch_16VYlI2eZvKYlo2CyajKjsYz 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
<Charge charge id=ch_16VYlI2eZvKYlo2CyajKjsYz at 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
Stripe\Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
com.stripe.model.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
&stripe.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}

Capture a charge

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

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

Arguments
  • id required

  • amount optional

    The amount to capture, which must be less than or equal to the original amount. Any additional amount will be automatically refunded.

  • application_fee optional

    An application fee to add on to this charge. Can only be used with Stripe Connect.

  • 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_16VYlI2eZvKYlo2CyajKjsYz/capture \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

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

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

ch, err := charge.Capture("ch_16VYlI2eZvKYlo2CyajKjsYz", nil)
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
#<Stripe::Charge id=ch_16VYlI2eZvKYlo2CyajKjsYz 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
<Charge charge id=ch_16VYlI2eZvKYlo2CyajKjsYz at 0x00000a> JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": "True",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
Stripe\Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
com.stripe.model.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": "true",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
{
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": "true",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}
&stripe.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": "true",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}

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.

  • 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_16VYlI2eZvKYlo2CyajKjsYz",
      "object": "charge",
      "created": 1438569192,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 30500,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
        "object": "card",
        "last4": "1111",
        "brand": "Visa",
        "funding": "unknown",
        "exp_month": 12,
        "exp_year": 2024,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": "pass",
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": null
      },
      "captured": true,
      "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": null,
      "invoice": null,
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "destination": null,
      "application_fee": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
        "data": [
    
        ]
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    #<Stripe::Charge id=ch_16VYlI2eZvKYlo2CyajKjsYz 0x00000a> JSON: {
      "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
      "object": "charge",
      "created": 1438569192,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 30500,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
        "object": "card",
        "last4": "1111",
        "brand": "Visa",
        "funding": "unknown",
        "exp_month": 12,
        "exp_year": 2024,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": "pass",
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": null
      },
      "captured": true,
      "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": null,
      "invoice": null,
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "destination": null,
      "application_fee": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
        "data": [
    
        ]
      }
    },
    #<Stripe::Charge[...] ...>,
    #<Stripe::Charge[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/charges",
  has_more: false,
  data: [
    <Charge charge id=ch_16VYlI2eZvKYlo2CyajKjsYz at 0x00000a> JSON: {
      "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
      "object": "charge",
      "created": 1438569192,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 30500,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
        "object": "card",
        "last4": "1111",
        "brand": "Visa",
        "funding": "unknown",
        "exp_month": 12,
        "exp_year": 2024,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": "pass",
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": null
      },
      "captured": true,
      "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": null,
      "invoice": null,
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "destination": null,
      "application_fee": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
        "data": [
    
        ]
      }
    },
    <stripe.Charge[...] ...>,
    <stripe.Charge[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/charges",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Charge JSON: {
      "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
      "object": "charge",
      "created": 1438569192,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 30500,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
        "object": "card",
        "last4": "1111",
        "brand": "Visa",
        "funding": "unknown",
        "exp_month": 12,
        "exp_year": 2024,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": "pass",
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": null
      },
      "captured": true,
      "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": null,
      "invoice": null,
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "destination": null,
      "application_fee": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
        "data": [
    
        ]
      }
    }
    [1] => <Stripe\Charge[...] ...>
    [2] => <Stripe\Charge[...] ...>
  ]
}
#<com.stripe.model.ChargeCollection id=#> JSON: {
  "data": [
    com.stripe.model.Charge JSON: {
      "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
      "object": "charge",
      "created": 1438569192,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 30500,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
        "object": "card",
        "last4": "1111",
        "brand": "Visa",
        "funding": "unknown",
        "exp_month": 12,
        "exp_year": 2024,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": "pass",
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": null
      },
      "captured": true,
      "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": null,
      "invoice": null,
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "destination": null,
      "application_fee": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
        "data": [
    
        ]
      }
    },
    #<com.stripe.model.Charge[...] ...>,
    #<com.stripe.model.Charge[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
      "object": "charge",
      "created": 1438569192,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 30500,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
        "object": "card",
        "last4": "1111",
        "brand": "Visa",
        "funding": "unknown",
        "exp_month": 12,
        "exp_year": 2024,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": "pass",
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": null
      },
      "captured": true,
      "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": null,
      "invoice": null,
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "destination": null,
      "application_fee": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
        "data": [
    
        ]
      }
    },
    {...},
    {...}
  ]
}
&stripe.Charge JSON: {
  "id": "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "object": "charge",
  "created": 1438569192,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 30500,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
    "object": "card",
    "last4": "1111",
    "brand": "Visa",
    "funding": "unknown",
    "exp_month": 12,
    "exp_year": 2024,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": "pass",
    "address_line1_check": null,
    "address_zip_check": null,
    "tokenization_method": null,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": null
  },
  "captured": true,
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "destination": null,
  "application_fee": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds",
    "data": [

    ]
  }
}

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 reversed, in cents.

  • created timestamp

  • currency currency

    Three-letter ISO code representing the currency of the reversal.

  • metadata metadata hash

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

  • balance_transaction string

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

  • charge string

    ID of the charge that was refunded.

  • description string

  • 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_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
#<Stripe::Refund id=re_16V8iT2eZvKYlo2C6FKmO3XF 0x00000a> JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
<Refund refund id=re_16V8iT2eZvKYlo2C6FKmO3XF at 0x00000a> JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
Stripe\Refund JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
com.stripe.model.Refund JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
{
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
&stripe.Refund JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": 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
  • amount optional, default is entire charge

    A positive integer in cents representing how much of this charge to refund. Can only refund up to the unrefunded amount remaining of the charge.

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

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

  • 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 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
ch = Stripe::Charge.retrieve({CHARGE_ID})
refund = ch.refunds.create
ch = stripe.Charge.retrieve({CHARGE_ID})
re = ch.refunds.create()
$ch = \Stripe\Charge::retrieve({CHARGE_ID});
$re = $ch->refunds->create();
Map params = new HashMap();
Charge ch = Charge.retrieve({CHARGE_ID});
Refund re = ch.getRefunds().create(params);
stripe.charges.createRefund(
  {CHARGE_ID},
  {},
  function(err, refund) {
  }
);
refund.New(&stripe.RefundParams{Charge: {CHARGE_ID}})
curl https://api.stripe.com/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_16VYlI2eZvKYlo2CyajKjsYz")
refund = ch.refunds.create
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_16VYlI2eZvKYlo2CyajKjsYz")
re = ch.refunds.create()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = \Stripe\Charge::retrieve("ch_16VYlI2eZvKYlo2CyajKjsYz");
$re = $ch->refunds->create();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> params = new HashMap<String, Object>();
Charge ch = Charge.retrieve("ch_16VYlI2eZvKYlo2CyajKjsYz");
Refund re = ch.getRefunds().create(params);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.createRefund(
  "ch_16VYlI2eZvKYlo2CyajKjsYz",
  { },
  function(err, refund) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := refund.New(&stripe.RefundParams{Charge: "ch_16VYlI2eZvKYlo2CyajKjsYz"})
{
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
#<Stripe::Refund id=re_16V8iT2eZvKYlo2C6FKmO3XF 0x00000a> JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
<Refund refund id=re_16V8iT2eZvKYlo2C6FKmO3XF at 0x00000a> JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
Stripe\Refund JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
com.stripe.model.Refund JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
{
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
&stripe.Refund JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}

Retrieve a refund

By default, you can see the 10 most recent refunds stored directly on the charge object, but you can also retrieve details about a specific refund stored on the charge.

Arguments
  • id required

    ID of refund to retrieve.

  • charge required

    ID of the charge refunded.

Returns

Returns the refund object.

curl https://api.stripe.com/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds/re_16V8iT2eZvKYlo2C6FKmO3XF \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = Stripe::Charge.retrieve("ch_16VYlI2eZvKYlo2CyajKjsYz")
refund = charge.refunds.retrieve("re_16V8iT2eZvKYlo2C6FKmO3XF")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = stripe.Charge.retrieve("ch_16VYlI2eZvKYlo2CyajKjsYz")
refund = charge.refunds.retrieve("re_16V8iT2eZvKYlo2C6FKmO3XF")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$charge = \Stripe\Charge::retrieve("ch_16VYlI2eZvKYlo2CyajKjsYz");
$refund = $charge->refunds->retrieve("re_16V8iT2eZvKYlo2C6FKmO3XF");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge ch = Charge.retrieve("ch_16VYlI2eZvKYlo2CyajKjsYz");
Refund refund = ch.getRefunds().retrieve("re_16V8iT2eZvKYlo2C6FKmO3XF");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.retrieveRefund(
  "ch_16VYlI2eZvKYlo2CyajKjsYz",
  "re_16V8iT2eZvKYlo2C6FKmO3XF",
  function(err, refund) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := refund.Get(
  "re_16V8iT2eZvKYlo2C6FKmO3XF",
  &stripe.RefundParams{Charge: "ch_16VYlI2eZvKYlo2CyajKjsYz"},
)
{
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
#<Stripe::Refund id=re_16V8iT2eZvKYlo2C6FKmO3XF 0x00000a> JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
<Refund refund id=re_16V8iT2eZvKYlo2C6FKmO3XF at 0x00000a> JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
Stripe\Refund JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
com.stripe.model.Refund JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
{
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": null
}
&stripe.Refund JSON: {
  "id": "re_16V8iT2eZvKYlo2C6FKmO3XF",
  "amount": 3671,
  "currency": "usd",
  "created": 1438469073,
  "object": "refund",
  "balance_transaction": "txn_16TLgJ2eZvKYlo2CjceoYOYo",
  "metadata": {
  },
  "charge": "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "receipt_number": null,
  "reason": 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/charges/{CHARGE_ID}/refunds/{REFUND_ID}
charge = Stripe::Charge.retrieve({CHARGE_ID})
refund = charge.refunds.retrieve({REFUND_ID})
refund.metadata[{KEY}] = {VALUE}
refund.save
charge = stripe.Charge.retrieve({CHARGE_ID})
refund = charge.refunds.retrieve({REFUND_ID})
refund.metadata[{KEY}] = {VALUE}
refund.save()
$charge = \Stripe\Charge::retrieve({CHARGE_ID});
$refund = $charge->refunds->retrieve({REFUND_ID});
$refund->metadata[{KEY}] = {VALUE};
$refund->save();
Charge ch = Charge.retrieve({CHARGE_ID});
Refund refund = cu.getRefunds().retrieve({REFUND_ID});
Map metadata = new HashMap();
metdata.put({KEY}, {VALUE});
Map params = new HashMap();
params.put("metadata", metadata);
refund.update(params);
stripe.charges.updateRefund({CHARGE_ID}, {REFUND_ID}, {
  metadata: {{KEY}: {VALUE}}
})
refund.Update({REFUND_ID}, &stripe.RefundParams{
  Charge: {CHARGE_ID}
  Meta: map[string]string{{KEY}: {VALUE}}
})
curl https://api.stripe.com/v1/charges/ch_16SbNZ2eZvKYlo2C5RR7O0Xi/refunds/re_16V8iT2eZvKYlo2C6FKmO3XF \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_16SbNZ2eZvKYlo2C5RR7O0Xi")
re = ch.refunds.retrieve("re_16V8iT2eZvKYlo2C6FKmO3XF")
re.metadata["key"] = "value"
re.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_16SbNZ2eZvKYlo2C5RR7O0Xi")
re = ch.refunds.retrieve("re_16V8iT2eZvKYlo2C6FKmO3XF")
re.metadata["key"] = "value"
re.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = \Stripe\Charge::retrieve("ch_16SbNZ2eZvKYlo2C5RR7O0Xi");
$re = $ch->refunds->retrieve("re_16V8iT2eZvKYlo2C6FKmO3XF");
$re->metadata["key"] = "value";
$re->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge ch = Charge.retrieve("ch_16SbNZ2eZvKYlo2C5RR7O0Xi");
Refund re = ch.getRefunds().retrieve("re_16V8iT2eZvKYlo2C6FKmO3XF");
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.charges.updateRefund(
  "ch_16SbNZ2eZvKYlo2C5RR7O0Xi",
  "re_16V8iT2eZvKYlo2C6FKmO3XF",
  { metadata: { key: "value"} },
  function(err, refund) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

List all refunds

You can see a list of the refunds belonging to a specific charge. Note that the 10 most recent refunds are always available by default on the charge 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 charge 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 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 customer ID or charge 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/charges/{CHARGE_ID}/refunds
Stripe::Charge.retrieve({CHARGE_ID}).refunds.all
stripe.Charge.retrieve({CHARGE_ID}).refunds.all()
\Stripe\Charge::retrieve({CHARGE_ID})->refunds->all();
Charge.retrieve({CHARGE_ID}).getRefunds().all();
stripe.charges.listRefunds(
  {CHARGE_ID},
  function(err, list) {...}
);
refund.List(&stripe.RefundListParams{Charge: {CHARGE_ID}})
curl https://api.stripe.com/v1/charges/ch_16VYlI2eZvKYlo2CyajKjsYz/refunds?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

Charge ch = Charge.retrieve("ch_16VYlI2eZvKYlo2CyajKjsYz");
Map<String, Object> refundParams = new HashMap<String, Object>();
refundParams.put("limit", 3);
ChargeRefundCollection refunds = ch.getRefunds().all(refundParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.listRefunds(
  "ch_16VYlI2eZvKYlo2CyajKjsYz",
  function(err, refunds) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

Customers

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

The customer object

Attributes
  • id string

  • object string , value is "customer"

  • livemode boolean

  • 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

  • metadata metadata hash

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

  • sources list

    The customer’s payment sources, if any

    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

    • url string

      The URL where this list can be accessed.

    • 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

  • subscriptions list

    The customer’s current subscriptions, if any

    child attributes
    • object string , value is "list"

    • data array, contains: subscription object

    • has_more boolean

    • url string

      The URL where this list can be accessed.

    • 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

  • 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

{
  "object": "customer",
  "created": 1438560411,
  "id": "cus_6iyQXxYdktOlra",
  "livemode": false,
  "description": "Customer",
  "email": "user1502@example.com",
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
    "data": [

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

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

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

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

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

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

    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
    "data": [
      {
        "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 8,
        "exp_year": 2019,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": null,
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_6iyQXxYdktOlra"
      }
    ]
  },
  "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
}

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.

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

    • number required

      The card number, as a string without any separators.

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

    • 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 optional, highly recommended

      Card security code.

    • name optional

      Cardholder's full name.

    • address_line1 optional

    • address_line2 optional

    • address_city optional

    • address_state optional

    • address_zip optional

    • address_country optional

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

  • 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_16V4wQ2eZvKYlo2CwPLkIJ82
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

\Stripe\Customer::create(array(
  "description" => "Customer for test@example.com",
  "source" => "tok_16V4wQ2eZvKYlo2CwPLkIJ82" // 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_16V4wQ2eZvKYlo2CwPLkIJ82"); // 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_16V4wQ2eZvKYlo2CwPLkIJ82" // 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_16V4wQ2eZvKYlo2CwPLkIJ82") // obtained with Stripe.js
c, err := customer.New(customerParams)
{
  "object": "customer",
  "created": 1438560411,
  "id": "cus_6iyQXxYdktOlra",
  "livemode": false,
  "description": "Customer",
  "email": "user1502@example.com",
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
    "data": [

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

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

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

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

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

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

    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
    "data": [
      {
        "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 8,
        "exp_year": 2019,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": null,
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_6iyQXxYdktOlra"
      }
    ]
  },
  "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
}

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
  • id required

    The identifier of the customer to be retrieved.

Returns

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

curl https://api.stripe.com/v1/customers/cus_6iyQXxYdktOlra \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

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

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

c, err := customer.Get("cus_6iyQXxYdktOlra", nil)
{
  "object": "customer",
  "created": 1438560411,
  "id": "cus_6iyQXxYdktOlra",
  "livemode": false,
  "description": "Customer",
  "email": "user1502@example.com",
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
    "data": [

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

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

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

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

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

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

    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
    "data": [
      {
        "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 8,
        "exp_year": 2019,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": null,
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_6iyQXxYdktOlra"
      }
    ]
  },
  "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
}

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.

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

    • number required

      The card number, as a string without any separators.

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

    • 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 optional, highly recommended

      Card security code.

    • name optional

      Cardholder's full name.

    • address_line1 optional

    • address_line2 optional

    • address_city optional

    • address_state optional

    • address_zip optional

    • address_country optional

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_6iyQXxYdktOlra \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Customer for test@example.com"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

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

c, err := customer.Update(
      "cus_6iyQXxYdktOlra",
      &stripe.CustomerParams{Desc: "Customer for test@example.com"},
    )
{
  "object": "customer",
  "created": 1438560411,
  "id": "cus_6iyQXxYdktOlra",
  "livemode": false,
  "description": "Customer for test@example.com",
  "email": "user1502@example.com",
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
    "data": [

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

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

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

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

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

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

    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
    "data": [
      {
        "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 8,
        "exp_year": 2019,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": null,
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_6iyQXxYdktOlra"
      }
    ]
  },
  "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
}

Delete a customer

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

Arguments
  • id required

    The identifier of the customer to be deleted.

Returns

Returns an object with a deleted parameter on success. If the customer ID does not exist, this call 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_6iyQXxYdktOlra \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

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

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

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

List all customers

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

Arguments
  • created optional 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": [
    {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    #<Stripe::Customer id=cus_6iyQXxYdktOlra 0x00000a> JSON: {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    },
    #<Stripe::Customer[...] ...>,
    #<Stripe::Customer[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers",
  has_more: false,
  data: [
    <Customer customer id=cus_6iyQXxYdktOlra at 0x00000a> JSON: {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    },
    <stripe.Customer[...] ...>,
    <stripe.Customer[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Customer JSON: {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    }
    [1] => <Stripe\Customer[...] ...>
    [2] => <Stripe\Customer[...] ...>
  ]
}
#<com.stripe.model.CustomerCollection id=#> JSON: {
  "data": [
    com.stripe.model.Customer JSON: {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    },
    #<com.stripe.model.Customer[...] ...>,
    #<com.stripe.model.Customer[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "object": "customer",
      "created": 1438560411,
      "id": "cus_6iyQXxYdktOlra",
      "livemode": false,
      "description": "Customer",
      "email": "user1502@example.com",
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
        "data": [
    
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
        "data": [
          {
            "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 8,
            "exp_year": 2019,
            "country": "US",
            "name": null,
            "address_line1": null,
            "address_line2": null,
            "address_city": null,
            "address_state": null,
            "address_zip": null,
            "address_country": null,
            "cvc_check": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "tokenization_method": null,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_6iyQXxYdktOlra"
          }
        ]
      },
      "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
    },
    {...},
    {...}
  ]
}
&stripe.Customer JSON: {
  "object": "customer",
  "created": 1438560411,
  "id": "cus_6iyQXxYdktOlra",
  "livemode": false,
  "description": "Customer",
  "email": "user1502@example.com",
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/subscriptions",
    "data": [

    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_6iyQXxYdktOlra/sources",
    "data": [
      {
        "id": "card_16VWTf2eZvKYlo2CwoIKccN6",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 8,
        "exp_year": 2019,
        "country": "US",
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "cvc_check": null,
        "address_line1_check": null,
        "address_zip_check": null,
        "tokenization_method": null,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_6iyQXxYdktOlra"
      }
    ]
  },
  "default_source": "card_16VWTf2eZvKYlo2CwoIKccN6"
}

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"

  • brand string

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

  • exp_month integer

  • exp_year integer

  • funding string

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

  • last4 string

  • metadata metadata hash

    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.

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

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

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

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

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

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

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

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

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

{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": null
}
#<Stripe::Card id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": null
}
<Card card id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": null
}
Stripe\Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": null
}
com.stripe.model.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": null
}
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": null
}
&stripe.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": 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".

    • number required

      The card number, as a string without any separators.

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

    • 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 optional, highly recommended

      Card security code.

    • name optional

      Cardholder's full name.

    • address_line1 optional

    • address_line2 optional

    • address_city optional

    • address_state optional

    • address_zip optional

    • address_country optional

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

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_6iyQXxYdktOlra/sources \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d source=token_id
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_6iyQXxYdktOlra")
customer.sources.create(:source => "tok_16V4wQ2eZvKYlo2CwPLkIJ82")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_6iyQXxYdktOlra")
customer.sources.create(source="tok_16V4wQ2eZvKYlo2CwPLkIJ82")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_6iyQXxYdktOlra");
$cu->sources->create(array("source" => "tok_16V4wQ2eZvKYlo2CwPLkIJ82"));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_6iyQXxYdktOlra");
Map<String, Object> params = new HashMap<String, Object>();
params.put("source", "tok_16V4wQ2eZvKYlo2CwPLkIJ82");
cu.createCard(params)
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.createSource(
  "cus_6iyQXxYdktOlra",
  {source: "tok_16V4wQ2eZvKYlo2CwPLkIJ82"},
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.New(&stripe.CardParams{
  Customer: "cus_6iyQXxYdktOlra",
  Token: "",
})
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
#<Stripe::Card id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
<Card card id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
Stripe\Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
com.stripe.model.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
&stripe.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
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_16UUrf2eZvKYlo2CGTJxYjum/cards \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d card=token_id
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum")
recipient.cards.create(:card => "tok_16V4wQ2eZvKYlo2CwPLkIJ82")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum")
recipient.cards.create(card="tok_16V4wQ2eZvKYlo2CwPLkIJ82")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Recipient::retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum");
$cu->cards->create(array("card" => "tok_16V4wQ2eZvKYlo2CwPLkIJ82"));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient cu = Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum");
Map<String, Object> params = new HashMap<String, Object>();
params.put("card", "tok_16V4wQ2eZvKYlo2CwPLkIJ82");
cu.createCard(params)
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.createCard(
  "rp_16UUrf2eZvKYlo2CGTJxYjum",
  {card: "tok_16V4wQ2eZvKYlo2CwPLkIJ82"},
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.New(&stripe.CardParams{
  Recipient: "rp_16UUrf2eZvKYlo2CGTJxYjum",
  Token: "tok_16V4wQ2eZvKYlo2CwPLkIJ82",
}
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
#<Stripe::Card id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
<Card card id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
Stripe\Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
com.stripe.model.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
&stripe.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}

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.

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_6iyQXxYdktOlra/sources/card_16VYlG2eZvKYlo2Cw7OfLlcl \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_6iyQXxYdktOlra")
card = customer.sources.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_6iyQXxYdktOlra")
card = customer.sources.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$customer = \Stripe\Customer::retrieve("cus_6iyQXxYdktOlra");
$card = $customer->sources->retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_6iyQXxYdktOlra");
PaymentSource source = cu.getSources().retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl");
if (source.getObject().equals("card")) {
  Card card = (Card) source;
  // use the card!
}
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.retrieveCard(
  "cus_6iyQXxYdktOlra",
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Get(
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  &stripe.CardParams{Customer: "cus_6iyQXxYdktOlra"},
)
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
#<Stripe::Card id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
<Card card id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
Stripe\Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
com.stripe.model.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
&stripe.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
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_16UUrf2eZvKYlo2CGTJxYjum/cards/card_16VYlG2eZvKYlo2Cw7OfLlcl \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum")
card = recipient.cards.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum")
card = recipient.cards.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$recipient = \Stripe\Recipient::retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum");
$card = $recipient->cards->retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient re = Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum");
Card card = re.getCards().retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.retrieveCard(
  "rp_16UUrf2eZvKYlo2CGTJxYjum",
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Get(
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  &stripe.CardParams{Recipient: "rp_16UUrf2eZvKYlo2CGTJxYjum"},
)
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
#<Stripe::Card id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
<Card card id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
Stripe\Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
com.stripe.model.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
&stripe.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}

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.

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_6iyQXxYdktOlra/sources/card_16VYlG2eZvKYlo2Cw7OfLlcl \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="Jane Austen"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_6iyQXxYdktOlra")
card = customer.sources.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl")
card.name = "Jane Austen"
card.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_6iyQXxYdktOlra")
card = customer.sources.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl")
card.name = "Jane Austen"
card.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_6iyQXxYdktOlra");
$card = $cu->sources->retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl");
$card->name = "Jane Austen";
$card->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_6iyQXxYdktOlra");
PaymentSource source = cu.getSources().retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl");
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_6iyQXxYdktOlra",
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  { name: "Jane Austen" },
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Update(
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  &stripe.CardParams{
    Customer: "cus_6iyQXxYdktOlra",
    Name: "Jane Austen",
  },
)
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
#<Stripe::Card id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
<Card card id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
Stripe\Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
com.stripe.model.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
&stripe.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
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_16UUrf2eZvKYlo2CGTJxYjum/cards/card_16VYlG2eZvKYlo2Cw7OfLlcl \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="Jane Austen"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum")
card = recipient.cards.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl")
card.name = "Jane Austen"
card.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum")
card = recipient.cards.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl")
card.name = "Jane Austen"
card.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$rp = \Stripe\Recipient::retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum");
$card = $rp->cards->retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl");
$card->name = "Jane Austen";
$card->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum");
Card card = rp.getCards().retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl");
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_16UUrf2eZvKYlo2CGTJxYjum",
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  { name: "Jane Austen" },
  function(err, card) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Update(
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  &stripe.CardParams{
    Recipient: "rp_16UUrf2eZvKYlo2CGTJxYjum",
    Name: "Jane Austen",
  },
)
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
#<Stripe::Card id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
<Card card id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
Stripe\Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
com.stripe.model.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
{
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}
&stripe.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": "Jane Austen",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}

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.

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_6iyQXxYdktOlra/sources/card_16VYlG2eZvKYlo2Cw7OfLlcl \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_6iyQXxYdktOlra")
customer.sources.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl").delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_6iyQXxYdktOlra")
customer.sources.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl").delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

Customer cu = Customer.retrieve("cus_6iyQXxYdktOlra");
for(PaymentSource source : cu.getSources().getData()){
  if(source.getId().equals("card_16VYlG2eZvKYlo2Cw7OfLlcl")){
    source.delete();
    break;
  }
}
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.deleteCard(
  "cus_6iyQXxYdktOlra",
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  function(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := card.Del(
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  &stripe.CardParams{Customer: "cus_6iyQXxYdktOlra"},
)
{
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl"
}
#<Stripe::Object id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl"
}
<Object object id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl"
}
com.stripe.model.Deletedcard JSON: {
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "deletedcard"
}
{
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl"
}
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_16UUrf2eZvKYlo2CGTJxYjum/cards/card_16VYlG2eZvKYlo2Cw7OfLlcl \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum")
recipient.cards.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl").delete()
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum")
recipient.cards.retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl").delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$rp = \Stripe\Recipient::retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum");
$rp->cards->retrieve("card_16VYlG2eZvKYlo2Cw7OfLlcl")->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum");
for(Card card : rp.getCards().getData()){
  if(card.getId().equals("card_16VYlG2eZvKYlo2Cw7OfLlcl")){
    card.delete();
    break;
  }
}
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.deleteCard(
  "rp_16UUrf2eZvKYlo2CGTJxYjum",
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  function(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := card.Del(
  "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  &stripe.CardParams{Recipient: "rp_16UUrf2eZvKYlo2CGTJxYjum"},
)
{
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl"
}
#<Stripe::Object id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl"
}
<Object object id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl"
}
com.stripe.model.Deletedcard JSON: {
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "deletedcard"
}
{
  "deleted": true,
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl"
}
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
  • id required

    The ID of the customer whose cards will be retrieved

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

Returns a list of the 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.

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{Customr: {CUSTOMER_ID})
curl https://api.stripe.com/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/sources?object=card&limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.retrieve("cu_16VWTf2eZvKYlo2Ctpwavs25").sources.all(:limit => 3, :object => "card")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.retrieve("cu_16VWTf2eZvKYlo2Ctpwavs25").sources.all(
  limit=3, object='card')
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::retrieve("cu_16VWTf2eZvKYlo2Ctpwavs25")->sources->all(array(
  'limit'=>3, 'object' => 'card'));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cu_16VWTf2eZvKYlo2Ctpwavs25");
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('cu_16VWTf2eZvKYlo2Ctpwavs25', function(err, cards) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CardListParams{Customer: "cu_16VWTf2eZvKYlo2Ctpwavs25"}
params.Filters.AddFilter("limit", "", "3")
i := card.List(params)
for i.Next() {
  c := i.Card()
}
{
  "object": "list",
  "url": "/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/sources",
  "has_more": false,
  "data": [
    {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_6iyQXxYdktOlra"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/sources",
  "has_more": false,
  "data": [
    #<Stripe::Card id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_6iyQXxYdktOlra"
    },
    #<Stripe::Card[...] ...>,
    #<Stripe::Card[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/sources",
  has_more: false,
  data: [
    <Card card id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_6iyQXxYdktOlra"
    },
    <stripe.Card[...] ...>,
    <stripe.Card[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/sources",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Card JSON: {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_6iyQXxYdktOlra"
    }
    [1] => <Stripe\Card[...] ...>
    [2] => <Stripe\Card[...] ...>
  ]
}
#<com.stripe.model.CardCollection id=#> JSON: {
  "data": [
    com.stripe.model.Card JSON: {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_6iyQXxYdktOlra"
    },
    #<com.stripe.model.Card[...] ...>,
    #<com.stripe.model.Card[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/sources",
  "has_more": false,
  "data": [
    {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_6iyQXxYdktOlra"
    },
    {...},
    {...}
  ]
}
&stripe.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_6iyQXxYdktOlra"
}
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_16UUrf2eZvKYlo2CGTJxYjum/cards?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum").cards.all(:limit => 3)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum").cards.all(
  limit=3)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Recipient::retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum")->cards->all(array(
  'limit'=>3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_16UUrf2eZvKYlo2CGTJxYjum");
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_16UUrf2eZvKYlo2CGTJxYjum', function(err, cards) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CardListParams{Recipient: "rp_16UUrf2eZvKYlo2CGTJxYjum"}
params.Filters.AddFilter("limit", "", "3")
i := card.List(params)
for i.Next() {
  c := i.Card()
}
{
  "object": "list",
  "url": "/v1/recipients/rp_16UUrf2eZvKYlo2CGTJxYjum/cards",
  "has_more": false,
  "data": [
    {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/recipients/rp_16UUrf2eZvKYlo2CGTJxYjum/cards",
  "has_more": false,
  "data": [
    #<Stripe::Card id=card_16VYlG2eZvKYlo2Cw7OfLlcl 0x00000a> JSON: {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
    },
    #<Stripe::Card[...] ...>,
    #<Stripe::Card[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/recipients/rp_16UUrf2eZvKYlo2CGTJxYjum/cards",
  has_more: false,
  data: [
    <Card card id=card_16VYlG2eZvKYlo2Cw7OfLlcl at 0x00000a> JSON: {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
    },
    <stripe.Card[...] ...>,
    <stripe.Card[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/recipients/rp_16UUrf2eZvKYlo2CGTJxYjum/cards",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Card JSON: {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
    }
    [1] => <Stripe\Card[...] ...>
    [2] => <Stripe\Card[...] ...>
  ]
}
#<com.stripe.model.CardCollection id=#> JSON: {
  "data": [
    com.stripe.model.Card JSON: {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
    },
    #<com.stripe.model.Card[...] ...>,
    #<com.stripe.model.Card[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/recipients/rp_16UUrf2eZvKYlo2CGTJxYjum/cards",
  "has_more": false,
  "data": [
    {
      "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
      "object": "card",
      "last4": "1111",
      "brand": "Visa",
      "funding": "unknown",
      "exp_month": 12,
      "exp_year": 2024,
      "country": "US",
      "name": null,
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "cvc_check": "pass",
      "address_line1_check": null,
      "address_zip_check": null,
      "tokenization_method": null,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
    },
    {...},
    {...}
  ]
}
&stripe.Card JSON: {
  "id": "card_16VYlG2eZvKYlo2Cw7OfLlcl",
  "object": "card",
  "last4": "1111",
  "brand": "Visa",
  "funding": "unknown",
  "exp_month": 12,
  "exp_year": 2024,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": "pass",
  "address_line1_check": null,
  "address_zip_check": null,
  "tokenization_method": null,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_16UUrf2eZvKYlo2CGTJxYjum"
}

Subscriptions

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

The subscription object

Attributes
  • id string

  • object string , value is "subscription"

  • cancel_at_period_end boolean

    If the subscription has been canceled with the at_period_end flag set to true, cancel_at_period_end on the subscription will be true. You can use this attribute to determine whether a subscription that has a status of active is scheduled to be canceled at the end of the current period.

  • customer string

  • metadata metadata hash

    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.

  • application_fee_percent decimal

    A positive decimal that represents the fee percentage of the subscription invoice amount that will be transferred to the application owner’s Stripe account each billing period.

  • canceled_at timestamp

    If the subscription has been canceled, the date of that cancellation. If the subscription was canceled with cancel_at_period_end, canceled_at will still reflect the date of the initial cancellation request, not the end of the subscription period when the subscription is automatically moved to a canceled state.

  • current_period_end timestamp

    End of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.

  • current_period_start timestamp

    Start of the current period that the subscription has been invoiced for

  • discount hash, discount object

    Describes the current discount applied to this subscription, if there is one. When billing, a discount applied to a subscription overrides a discount applied on a customer-wide basis.

  • ended_at timestamp

    If the subscription has ended (either because it was canceled or because the customer was switched to a subscription to a new plan), the date the subscription ended

  • 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_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
#<Stripe::StripeObject id=sub_6j0qn6K5MouxnK 0x00000a> JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
<StripeObject subscription id=sub_6j0qn6K5MouxnK at 0x00000a> JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
Stripe\StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
com.stripe.model.StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
{
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
&stripe.StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}

Create a subscription

Creates a new subscription on an existing customer.

Arguments
  • plan required

    The identifier of the plan to subscribe the customer to.

  • coupon optional, default is 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.

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

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

    • numbernumbernumbernumbernumbernumbernumber required

      The 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 optional, highly recommended

      Card security code.

    • namenamenamenamenamenamename optional

      Cardholder's full name.

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

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

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

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

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

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_6iyQXxYdktOlra/subscriptions \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d plan=gold21323
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_6iyQXxYdktOlra")
customer.subscriptions.create(:plan => "gold21323")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_6iyQXxYdktOlra")
customer.subscriptions.create(plan="gold21323")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_6iyQXxYdktOlra");
$cu->subscriptions->create(array("plan" => "gold21323"));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_6iyQXxYdktOlra");
Map<String, Object> params = new HashMap<String, Object>();
params.put("plan", "gold21323");
cu.createSubscription(params)
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.createSubscription(
  "cus_6iyQXxYdktOlra",
  {plan: "gold21323"},
  function(err, subscription) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

s, err := sub.New(&stripe.SubParams{
  Customer: "cus_6iyQXxYdktOlra",
  Plan: "gold21323",
})
{
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
#<Stripe::StripeObject id=sub_6j0qn6K5MouxnK 0x00000a> JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
<StripeObject subscription id=sub_6j0qn6K5MouxnK at 0x00000a> JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
Stripe\StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
com.stripe.model.StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
{
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
&stripe.StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}

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
  • id required

    ID of subscription to retrieve.

  • customer required

Returns

Returns the subscription object.

curl https://api.stripe.com/v1/customers/cus_6iyQXxYdktOlra/subscriptions/sub_6j0qn6K5MouxnK \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_6iyQXxYdktOlra")
subscription = customer.subscriptions.retrieve("sub_6j0qn6K5MouxnK")
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_6iyQXxYdktOlra")
subscription = customer.subscriptions.retrieve("sub_6j0qn6K5MouxnK")
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$customer = \Stripe\Customer::retrieve("cus_6iyQXxYdktOlra");
$subscription = $customer->subscriptions->retrieve("sub_6j0qn6K5MouxnK");
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_6iyQXxYdktOlra");
Subscription subscription = cu.getSubscriptions().retrieve("sub_6j0qn6K5MouxnK");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.retrieveSubscription(
  "cus_6iyQXxYdktOlra",
  "sub_6j0qn6K5MouxnK",
  function(err, subscription) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

s, err := sub.Get(
  "sub_6j0qn6K5MouxnK",
  &stripe.SubParams{Customer: "cus_6iyQXxYdktOlra"},
)
{
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
#<Stripe::StripeObject id=sub_6j0qn6K5MouxnK 0x00000a> JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
<StripeObject subscription id=sub_6j0qn6K5MouxnK at 0x00000a> JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
Stripe\StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
com.stripe.model.StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
{
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
&stripe.StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}

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

    The identifier of the plan to update the subscription to. If omitted, the subscription will not change plans.

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

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

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

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

    • numbernumbernumbernumbernumbernumbernumber required

      The 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 optional, highly recommended

      Card security code.

    • namenamenamenamenamenamename optional

      Cardholder's full name.

    • address_line1address_line1address_line1address_line1address_line1address_line1address_line1 optional

    • address_line2address_line2address_line2address_line2address_line2address_line2address_line2 optional

    • address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip optional

    • address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state optional

    • address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country optional

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

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

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

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

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 raises 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_6iyQXxYdktOlra/subscriptions/sub_6j0qn6K5MouxnK \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d plan=gold21323
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_6iyQXxYdktOlra")
subscription = customer.subscriptions.retrieve("sub_6j0qn6K5MouxnK")
subscription.plan = "gold21323"
subscription.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_6iyQXxYdktOlra")
subscription = customer.subscriptions.retrieve("sub_6j0qn6K5MouxnK")
subscription.plan = "gold21323"
subscription.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_6iyQXxYdktOlra");
$subscription = $cu->subscriptions->retrieve("sub_6j0qn6K5MouxnK");
$subscription->plan = "gold21323";
$subscription->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_6iyQXxYdktOlra");
Subscription subscription = cu.getSubscriptions().retrieve("sub_6j0qn6K5MouxnK");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("plan", "gold21323");
subscription.update(updateParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.updateSubscription(
  "cus_6iyQXxYdktOlra",
  "sub_6j0qn6K5MouxnK",
  { plan: "gold21323" },
  function(err, subscription) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

s, err := sub.Update(
      "sub_6j0qn6K5MouxnK",
      &stripe.SubParams{
        Customer: "cus_6iyQXxYdktOlra",
        Plan: "gold21323",
      },
    )
{
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
#<Stripe::StripeObject id=sub_6j0qn6K5MouxnK 0x00000a> JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
<StripeObject subscription id=sub_6j0qn6K5MouxnK at 0x00000a> JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
Stripe\StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
com.stripe.model.StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
{
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
&stripe.StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}

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_6iyQXxYdktOlra/subscriptions/sub_6j0qn6K5MouxnK \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_6iyQXxYdktOlra")
customer.subscriptions.retrieve("sub_6j0qn6K5MouxnK").delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_6iyQXxYdktOlra")
customer.subscriptions.retrieve("sub_6j0qn6K5MouxnK").delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_6iyQXxYdktOlra");
$cu->subscriptions->retrieve("sub_6j0qn6K5MouxnK")->cancel();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_6iyQXxYdktOlra");
for(Subscription subscription : cu.getSubscriptions().getData()){
  if(subscription.getId().equals("sub_6j0qn6K5MouxnK")){
    subscription.cancel(null);
    break;
  }
}
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.cancelSubscription(
  "cus_6iyQXxYdktOlra",
  "sub_6j0qn6K5MouxnK",
  function(err, confirmation) {
    // asynchronously called
  }
);
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := sub.Cancel(
  "sub_6j0qn6K5MouxnK",
  &stripe.SubParams{Customer: "cus_6iyQXxYdktOlra"},
)
{
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "canceled",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
#<Stripe::StripeObject id=sub_6j0qn6K5MouxnK 0x00000a> JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "canceled",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
<StripeObject subscription id=sub_6j0qn6K5MouxnK at 0x00000a> JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "canceled",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
Stripe\StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "canceled",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
com.stripe.model.Deletedsubscription JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "deletedsubscription",
  "start": 1438569386,
  "status": "canceled",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
{
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "canceled",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}
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
  • id required

    The ID of the customer whose subscriptions will be retrieved

  • ending_before optional

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • limit optional, default is 10

    A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

  • starting_after optional

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

Returns a list of the customer's active subscriptions.

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

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/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/cu_16VWTf2eZvKYlo2Ctpwavs25/subscriptions?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

\Stripe\Customer::retrieve("cu_16VWTf2eZvKYlo2Ctpwavs25")->subscriptions->all(array(
  'limit'=>3));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cu_16VWTf2eZvKYlo2Ctpwavs25");
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('cu_16VWTf2eZvKYlo2Ctpwavs25', function(err, subscriptions) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.SubListParams{Customer: "cu_16VWTf2eZvKYlo2Ctpwavs25"}
params.Filters.AddFilter("limit", "", "3")
i := sub.List(params)
for i.Next() {
  s := i.Sub()
}
{
  "object": "list",
  "url": "/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/subscriptions",
  "has_more": false,
  "data": [
    {
      "id": "sub_6j0qn6K5MouxnK",
      "plan": {
        "interval": "month",
        "name": "New plan name",
        "created": 1386247539,
        "amount": 2000,
        "currency": "usd",
        "id": "gold21323",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1438569386,
      "status": "active",
      "customer": "cus_6iyQXxYdktOlra",
      "cancel_at_period_end": false,
      "current_period_start": 1438569386,
      "current_period_end": 1441247786,
      "ended_at": null,
      "trial_start": null,
      "trial_end": null,
      "canceled_at": null,
      "quantity": 1,
      "application_fee_percent": null,
      "discount": null,
      "tax_percent": null,
      "metadata": {
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/subscriptions",
  "has_more": false,
  "data": [
    #<Stripe::StripeObject id=sub_6j0qn6K5MouxnK 0x00000a> JSON: {
      "id": "sub_6j0qn6K5MouxnK",
      "plan": {
        "interval": "month",
        "name": "New plan name",
        "created": 1386247539,
        "amount": 2000,
        "currency": "usd",
        "id": "gold21323",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1438569386,
      "status": "active",
      "customer": "cus_6iyQXxYdktOlra",
      "cancel_at_period_end": false,
      "current_period_start": 1438569386,
      "current_period_end": 1441247786,
      "ended_at": null,
      "trial_start": null,
      "trial_end": null,
      "canceled_at": null,
      "quantity": 1,
      "application_fee_percent": null,
      "discount": null,
      "tax_percent": null,
      "metadata": {
      }
    },
    #<Stripe::Subscription[...] ...>,
    #<Stripe::Subscription[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/subscriptions",
  has_more: false,
  data: [
    <StripeObject subscription id=sub_6j0qn6K5MouxnK at 0x00000a> JSON: {
      "id": "sub_6j0qn6K5MouxnK",
      "plan": {
        "interval": "month",
        "name": "New plan name",
        "created": 1386247539,
        "amount": 2000,
        "currency": "usd",
        "id": "gold21323",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1438569386,
      "status": "active",
      "customer": "cus_6iyQXxYdktOlra",
      "cancel_at_period_end": false,
      "current_period_start": 1438569386,
      "current_period_end": 1441247786,
      "ended_at": null,
      "trial_start": null,
      "trial_end": null,
      "canceled_at": null,
      "quantity": 1,
      "application_fee_percent": null,
      "discount": null,
      "tax_percent": null,
      "metadata": {
      }
    },
    <stripe.Subscription[...] ...>,
    <stripe.Subscription[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/subscriptions",
  "has_more" => false,
  "data" => [
    [0] => Stripe\StripeObject JSON: {
      "id": "sub_6j0qn6K5MouxnK",
      "plan": {
        "interval": "month",
        "name": "New plan name",
        "created": 1386247539,
        "amount": 2000,
        "currency": "usd",
        "id": "gold21323",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1438569386,
      "status": "active",
      "customer": "cus_6iyQXxYdktOlra",
      "cancel_at_period_end": false,
      "current_period_start": 1438569386,
      "current_period_end": 1441247786,
      "ended_at": null,
      "trial_start": null,
      "trial_end": null,
      "canceled_at": null,
      "quantity": 1,
      "application_fee_percent": null,
      "discount": null,
      "tax_percent": null,
      "metadata": {
      }
    }
    [1] => <Stripe\Subscription[...] ...>
    [2] => <Stripe\Subscription[...] ...>
  ]
}
#<com.stripe.model.SubscriptionCollection id=#> JSON: {
  "data": [
    com.stripe.model.StripeObject JSON: {
      "id": "sub_6j0qn6K5MouxnK",
      "plan": {
        "interval": "month",
        "name": "New plan name",
        "created": 1386247539,
        "amount": 2000,
        "currency": "usd",
        "id": "gold21323",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1438569386,
      "status": "active",
      "customer": "cus_6iyQXxYdktOlra",
      "cancel_at_period_end": false,
      "current_period_start": 1438569386,
      "current_period_end": 1441247786,
      "ended_at": null,
      "trial_start": null,
      "trial_end": null,
      "canceled_at": null,
      "quantity": 1,
      "application_fee_percent": null,
      "discount": null,
      "tax_percent": null,
      "metadata": {
      }
    },
    #<com.stripe.model.Subscription[...] ...>,
    #<com.stripe.model.Subscription[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers/cu_16VWTf2eZvKYlo2Ctpwavs25/subscriptions",
  "has_more": false,
  "data": [
    {
      "id": "sub_6j0qn6K5MouxnK",
      "plan": {
        "interval": "month",
        "name": "New plan name",
        "created": 1386247539,
        "amount": 2000,
        "currency": "usd",
        "id": "gold21323",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1438569386,
      "status": "active",
      "customer": "cus_6iyQXxYdktOlra",
      "cancel_at_period_end": false,
      "current_period_start": 1438569386,
      "current_period_end": 1441247786,
      "ended_at": null,
      "trial_start": null,
      "trial_end": null,
      "canceled_at": null,
      "quantity": 1,
      "application_fee_percent": null,
      "discount": null,
      "tax_percent": null,
      "metadata": {
      }
    },
    {...},
    {...}
  ]
}
&stripe.StripeObject JSON: {
  "id": "sub_6j0qn6K5MouxnK",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1438569386,
  "status": "active",
  "customer": "cus_6iyQXxYdktOlra",
  "cancel_at_period_end": false,
  "current_period_start": 1438569386,
  "current_period_end": 1441247786,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null,
  "tax_percent": null,
  "metadata": {
  }
}

Plans

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

The plan object

Attributes
  • id string

  • object string , value is "plan"

  • livemode boolean

  • amount positive integer or zero

    The amount in cents to be charged on the interval specified

  • created timestamp

  • currency currency

    Currency in which subscription will be charged

  • interval interval string

    One of 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.

  • metadata metadata hash

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

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

{
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
#<Stripe::Plan id=gold21323 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
<Plan plan id=gold21323 at 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
Stripe\Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
com.stripe.model.Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
{
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
&stripe.Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": 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.

  • interval_count optional, default is 1

    The number of intervals between each subscription billing. For example, interval=month and interval_count=3 bills every 3 months. Maximum of one year interval allowed (1 year, 12 months, or 52 weeks).

  • name required

    Name of the plan, to be displayed on invoices and in the web interface.

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

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",
})
{
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
#<Stripe::Plan id=gold21323 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
<Plan plan id=gold21323 at 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
Stripe\Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
com.stripe.model.Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
{
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
&stripe.Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

Retrieve a plan

Retrieves the plan with the given ID.

Arguments
  • id required

    The ID of the desired plan.

Returns

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

curl https://api.stripe.com/v1/plans/gold21323 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

Plan.retrieve("gold21323");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

p, err := plan.Get("gold21323", nil)
{
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
#<Stripe::Plan id=gold21323 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
<Plan plan id=gold21323 at 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
Stripe\Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
com.stripe.model.Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
{
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
&stripe.Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

Update a plan

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

Arguments
  • id 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/gold21323 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="New plan name"
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p = Stripe::Plan.retrieve("gold21323")
p.name = "New plan name"
p.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p = stripe.Plan.retrieve("gold21323")
p.name = "New plan name"
p.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$p = \Stripe\Plan::retrieve("gold21323");
$p->name = "New plan name";
$p->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Plan p = Plan.retrieve("gold21323");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("name", "New plan name");
p.update(updateParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.plans.update("gold21323", {
  name: "New plan name"
}, function(err, plan) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p, err := plan.Update(
      "gold21323",
      &stripe.PlanParams{Name: "New plan name"},
    )
{
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
#<Stripe::Plan id=gold21323 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
<Plan plan id=gold21323 at 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
Stripe\Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
com.stripe.model.Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
{
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}
&stripe.Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": 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
  • id required

    The identifier of the plan to be deleted.

Returns

An object with the deleted plan's ID and a deleted flag upon success. Otherwise, this call 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/gold21323 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

plan = Stripe::Plan.retrieve("gold21323")
plan.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

plan = stripe.Plan.retrieve("gold21323")
plan.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$plan = \Stripe\Plan::retrieve("gold21323");
$plan->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Plan plan = Plan.retrieve("gold21323");
plan.delete();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

err := plan.Del("gold21323")
{
  "deleted": true,
  "id": "gold21323"
}
#<Stripe::Object id=gold21323 0x00000a> JSON: {
  "deleted": true,
  "id": "gold21323"
}
<Object object id=gold21323 at 0x00000a> JSON: {
  "deleted": true,
  "id": "gold21323"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "gold21323"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "gold21323"
}
{
  "deleted": true,
  "id": "gold21323"
}
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. 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": [
    {
      "interval": "month",
      "name": "New plan name",
      "created": 1386247539,
      "amount": 2000,
      "currency": "usd",
      "id": "gold21323",
      "object": "plan",
      "livemode": false,
      "interval_count": 1,
      "trial_period_days": null,
      "metadata": {
      },
      "statement_descriptor": null
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/plans",
  "has_more": false,
  "data": [
    #<Stripe::Plan id=gold21323 0x00000a> JSON: {
      "interval": "month",
      "name": "New plan name",
      "created": 1386247539,
      "amount": 2000,
      "currency": "usd",
      "id": "gold21323",
      "object": "plan",
      "livemode": false,
      "interval_count": 1,
      "trial_period_days": null,
      "metadata": {
      },
      "statement_descriptor": null
    },
    #<Stripe::Plan[...] ...>,
    #<Stripe::Plan[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/plans",
  has_more: false,
  data: [
    <Plan plan id=gold21323 at 0x00000a> JSON: {
      "interval": "month",
      "name": "New plan name",
      "created": 1386247539,
      "amount": 2000,
      "currency": "usd",
      "id": "gold21323",
      "object": "plan",
      "livemode": false,
      "interval_count": 1,
      "trial_period_days": null,
      "metadata": {
      },
      "statement_descriptor": null
    },
    <stripe.Plan[...] ...>,
    <stripe.Plan[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/plans",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Plan JSON: {
      "interval": "month",
      "name": "New plan name",
      "created": 1386247539,
      "amount": 2000,
      "currency": "usd",
      "id": "gold21323",
      "object": "plan",
      "livemode": false,
      "interval_count": 1,
      "trial_period_days": null,
      "metadata": {
      },
      "statement_descriptor": null
    }
    [1] => <Stripe\Plan[...] ...>
    [2] => <Stripe\Plan[...] ...>
  ]
}
#<com.stripe.model.PlanCollection id=#> JSON: {
  "data": [
    com.stripe.model.Plan JSON: {
      "interval": "month",
      "name": "New plan name",
      "created": 1386247539,
      "amount": 2000,
      "currency": "usd",
      "id": "gold21323",
      "object": "plan",
      "livemode": false,
      "interval_count": 1,
      "trial_period_days": null,
      "metadata": {
      },
      "statement_descriptor": null
    },
    #<com.stripe.model.Plan[...] ...>,
    #<com.stripe.model.Plan[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/plans",
  "has_more": false,
  "data": [
    {
      "interval": "month",
      "name": "New plan name",
      "created": 1386247539,
      "amount": 2000,
      "currency": "usd",
      "id": "gold21323",
      "object": "plan",
      "livemode": false,
      "interval_count": 1,
      "trial_period_days": null,
      "metadata": {
      },
      "statement_descriptor": null
    },
    {...},
    {...}
  ]
}
&stripe.Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

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"

  • livemode boolean

  • created timestamp

  • duration coupon duration string

    One of forever, once, and repeating. Describes how long a customer who applies this coupon will get the discount.

  • metadata metadata hash

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

  • 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

  • amount_off positive integer

    Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer.

  • currency currency

    If amount_off has been set, the currency of the amount to take off.

  • duration_in_months positive integer

    If duration is repeating, the number of months the coupon applies. Null if coupon duration is forever or once.

  • max_redemptions positive integer

    Maximum number of times this coupon can be redeemed, in total, before it is no longer valid.

  • 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

{
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
#<Stripe::Coupon id=grandfathered 0x00000a> JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
<Coupon coupon id=grandfathered at 0x00000a> JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
Stripe\Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
com.stripe.model.Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
{
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
&stripe.Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}

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 a customer. This is often a specific code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you can leave the ID blank and we’ll generate a random code for you.

  • duration required

    Specifies how long the discount will be in effect. Can be forever, once, or repeating.

  • amount_off optional

    A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed)

  • currency optional

    Currency of the amount_off parameter (required if amount_off is passed)

  • duration_in_months optional

    required only if duration is repeating If duration is repeating, a positive integer that specifies the number of months the discount will be in effect

  • max_redemptions optional

    A positive integer specifying the number of times the coupon can be redeemed before it’s no longer valid. For example, you might have a 50% off coupon that the first 20 readers of your blog can use.

  • metadata optional

    A set of key/value pairs that you can attach to a coupon object. It can be useful for storing additional information about the coupon in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to 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": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
#<Stripe::Coupon id=grandfathered 0x00000a> JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
<Coupon coupon id=grandfathered at 0x00000a> JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
Stripe\Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
com.stripe.model.Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
{
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
&stripe.Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}

Retrieve a coupon

Retrieves the coupon with the given ID.

Arguments
  • id required

    The ID of the desired coupon.

Returns

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

curl https://api.stripe.com/v1/coupons/grandfathered \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

Coupon.retrieve("grandfathered");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

c, err := coupon.Get("grandfathered", nil)
{
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
#<Stripe::Coupon id=grandfathered 0x00000a> JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
<Coupon coupon id=grandfathered at 0x00000a> JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
Stripe\Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
com.stripe.model.Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
{
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}
&stripe.Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}

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/grandfathered \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

coupon = Stripe::Coupon.retrieve("grandfathered")
coupon.metadata["key"] = "value"
coupon.save
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

coupon = stripe.Coupon.retrieve("grandfathered")
coupon.metadata["key"] = "value"
coupon.save()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$coupon = \Stripe\Coupon::retrieve("grandfathered");
$coupon->metadata["key"] = "value";
$coupon->save();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon coupon = Coupon.retrieve("grandfathered");
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("grandfathered", {
  metadata: {key: "value"}
)
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := coupon.Update(
      "grandfathered",
      &stripe.CouponParams{Meta: map[string]string{"key": "value"}},
)
{
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
    "key": "value"
  }
}
#<Stripe::Coupon id=grandfathered 0x00000a> JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
    "key": "value"
  }
}
<Coupon coupon id=grandfathered at 0x00000a> JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
    "key": "value"
  }
}
Stripe\Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
    "key": "value"
  }
}
com.stripe.model.Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
    "key": "value"
  }
}
{
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
    "key": "value"
  }
}
&stripe.Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
    "key": "value"
  }
}

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
  • id required

    The identifier of the coupon to be deleted.

Returns

An object with the deleted coupon's ID and a deleted flag upon success. Otherwise, this call 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/grandfathered \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cpn = Stripe::Coupon.retrieve("grandfathered")
cpn.delete
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cpn = stripe.Coupon.retrieve("grandfathered")
cpn.delete()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cpn = \Stripe\Coupon::retrieve("grandfathered");
$cpn->delete();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon cpn = Coupon.retrieve("grandfathered");
cpn.delete();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.del("grandfathered")
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := coupon.Del("grandfathered")
{
  "deleted": true,
  "id": "grandfathered"
}
#<Stripe::Object id=grandfathered 0x00000a> JSON: {
  "deleted": true,
  "id": "grandfathered"
}
<Object object id=grandfathered at 0x00000a> JSON: {
  "deleted": true,
  "id": "grandfathered"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "grandfathered"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "grandfathered"
}
{
  "deleted": true,
  "id": "grandfathered"
}
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. 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": "grandfathered",
      "created": 1437556338,
      "percent_off": 24,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "forever",
      "redeem_by": null,
      "max_redemptions": null,
      "times_redeemed": 2,
      "duration_in_months": null,
      "valid": true,
      "metadata": {
      }
    },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "url": "/v1/coupons",
  "has_more": false,
  "data": [
    #<Stripe::Coupon id=grandfathered 0x00000a> JSON: {
      "id": "grandfathered",
      "created": 1437556338,
      "percent_off": 24,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "forever",
      "redeem_by": null,
      "max_redemptions": null,
      "times_redeemed": 2,
      "duration_in_months": null,
      "valid": true,
      "metadata": {
      }
    },
    #<Stripe::Coupon[...] ...>,
    #<Stripe::Coupon[...] ...>
  ]
}
{
  object: "list",
  url: "/v1/coupons",
  has_more: false,
  data: [
    <Coupon coupon id=grandfathered at 0x00000a> JSON: {
      "id": "grandfathered",
      "created": 1437556338,
      "percent_off": 24,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "forever",
      "redeem_by": null,
      "max_redemptions": null,
      "times_redeemed": 2,
      "duration_in_months": null,
      "valid": true,
      "metadata": {
      }
    },
    <stripe.Coupon[...] ...>,
    <stripe.Coupon[...] ...>
  ]
}
Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/coupons",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Coupon JSON: {
      "id": "grandfathered",
      "created": 1437556338,
      "percent_off": 24,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "forever",
      "redeem_by": null,
      "max_redemptions": null,
      "times_redeemed": 2,
      "duration_in_months": null,
      "valid": true,
      "metadata": {
      }
    }
    [1] => <Stripe\Coupon[...] ...>
    [2] => <Stripe\Coupon[...] ...>
  ]
}
#<com.stripe.model.CouponCollection id=#> JSON: {
  "data": [
    com.stripe.model.Coupon JSON: {
      "id": "grandfathered",
      "created": 1437556338,
      "percent_off": 24,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "forever",
      "redeem_by": null,
      "max_redemptions": null,
      "times_redeemed": 2,
      "duration_in_months": null,
      "valid": true,
      "metadata": {
      }
    },
    #<com.stripe.model.Coupon[...] ...>,
    #<com.stripe.model.Coupon[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/coupons",
  "has_more": false,
  "data": [
    {
      "id": "grandfathered",
      "created": 1437556338,
      "percent_off": 24,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "forever",
      "redeem_by": null,
      "max_redemptions": null,
      "times_redeemed": 2,
      "duration_in_months": null,
      "valid": true,
      "metadata": {
      }
    },
    {...},
    {...}
  ]
}
&stripe.Coupon JSON: {
  "id": "grandfathered",
  "created": 1437556338,
  "percent_off": 24,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": null,
  "max_redemptions": null,
  "times_redeemed": 2,
  "duration_in_months": null,
  "valid": true,
  "metadata": {
  }
}

Discounts

A discount represents the actual application of a coupon to a particular customer. It contains information about when the discount began and when it will end.

The discount object

Attributes
  • object string , value is "discount"

  • coupon hash, coupon object

    Hash describing the coupon applied to create this discount

  • customer string

  • start timestamp

    Date that the coupon was applied

  • end timestamp

    If the coupon has a duration of once or repeating, the date that this discount will end. If the coupon used has a forever duration, this attribute will be null.

  • subscription string

    The subscription that this coupon is applied to, if it is applied to a particular subscription

{
  "coupon": {
    "id": "grandfathered",
    "created": 1437556338,
    "percent_off": 24,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": null,
    "max_redemptions": null,
    "times_redeemed": 2,
    "duration_in_months": null,
    "valid": true,
    "metadata": {
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_6iyQXxYdktOlra",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}
#<Stripe::Discount 0x00000a> JSON: {
  "coupon": {
    "id": "grandfathered",
    "created": 1437556338,
    "percent_off": 24,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": null,
    "max_redemptions": null,
    "times_redeemed": 2,
    "duration_in_months": null,
    "valid": true,
    "metadata": {
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_6iyQXxYdktOlra",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}
<Discount discount at 0x00000a> JSON: {
  "coupon": {
    "id": "grandfathered",
    "created": 1437556338,
    "percent_off": 24,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": null,
    "max_redemptions": null,
    "times_redeemed": 2,
    "duration_in_months": null,
    "valid": true,
    "metadata": {
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_6iyQXxYdktOlra",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}
Stripe\Discount JSON: {
  "coupon": {
    "id": "grandfathered",
    "created": 1437556338,
    "percent_off": 24,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": null,
    "max_redemptions": null,
    "times_redeemed": 2,
    "duration_in_months": null,
    "valid": true,
    "metadata": {
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_6iyQXxYdktOlra",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}
com.stripe.model.Discount JSON: {
  "coupon": {
    "id": "grandfathered",
    "created": 1437556338,
    "percent_off": 24,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": null,
    "max_redemptions": null,
    "times_redeemed": 2,
    "duration_in_months": null,
    "valid": true,
    "metadata": {
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_6iyQXxYdktOlra",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}
{
  "coupon": {
    "id": "grandfathered",
    "created": 1437556338,
    "percent_off": 24,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": null,
    "max_redemptions": null,
    "times_redeemed": 2,
    "duration_in_months": null,
    "valid": true,
    "metadata": {
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_6iyQXxYdktOlra",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}
&stripe.Discount JSON: {
  "coupon": {
    "id": "grandfathered",
    "created": 1437556338,
    "percent_off": 24,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": null,
    "max_redemptions": null,
    "times_redeemed": 2,
    "duration_in_months": null,
    "valid": true,
    "metadata": {
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_6iyQXxYdktOlra",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": 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 returnsraisesraisesthrowsthrowsthrowsreturns 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_6iyQXxYdktOlra/discount \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_6iyQXxYdktOlra")
cu.delete_discount
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_6iyQXxYdktOlra")
cu.delete_discount()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

Customer cu = Customer.retrieve("cus_6iyQXxYdktOlra");
cu.deleteDiscount();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

err := discount.Del("cus_6iyQXxYdktOlra")
{
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
#<Stripe::Object id=di_14Rjd02eZvKYlo2Cl8SvGHtJ 0x00000a> JSON: {
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
<Object object id=di_14Rjd02eZvKYlo2Cl8SvGHtJ at 0x00000a> JSON: {
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
{
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
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 returnsraisesraisesthrowsthrowsthrowsreturns 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_6iyQXxYdktOlra/subscriptions/sub_6j0qn6K5MouxnK/discount \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_6iyQXxYdktOlra")
cu.subscriptions.retrieve("sub_6j0qn6K5MouxnK").delete_discount()
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_6iyQXxYdktOlra")
cu.subscriptions.retrieve("sub_6j0qn6K5MouxnK").delete_discount()
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_6iyQXxYdktOlra");
$cu->subscriptions->retrieve("sub_6j0qn6K5MouxnK")->deleteDiscount();
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_6iyQXxYdktOlra");
cu.subscriptions.retrieve("sub_6j0qn6K5MouxnK").deleteDiscount();
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.deleteSubscriptionDiscount("cus_6iyQXxYdktOlra", "sub_6j0qn6K5MouxnK", function(err, confirmation) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := discount.DelSub(
      "cus_6iyQXxYdktOlra",
      "sub_6j0qn6K5MouxnK",
)
{
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
#<Stripe::Object id=di_14Rjd02eZvKYlo2Cl8SvGHtJ 0x00000a> JSON: {
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
<Object object id=di_14Rjd02eZvKYlo2Cl8SvGHtJ at 0x00000a> JSON: {
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
Stripe\Object JSON: {
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
{
  "deleted": true,
  "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
}
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"

  • livemode boolean

  • amount_due integer

    Final amount due at this time for this invoice. If the invoice’s total is smaller than the minimum charge amount, for example, or if there is account credit that can be applied to the invoice, the amount_due may be 0. If there is a positive starting_balance for the invoice (the customer owes money), the amount_due will also take that into account. The charge that gets generated for the invoice will be for the amount specified in amount_due.

  • attempt_count positive integer or zero

    Number of 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.

  • 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

  • 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

    • url string

      The URL where this list can be accessed.

    • 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

  • 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

  • starting_balance integer

    Starting customer balance before attempting to pay invoice. If the invoice has not been attempted yet, this will be the current customer balance.

  • subtotal integer

    Total of all subscriptions, invoice items, and prorations on the invoice before any discount is applied

  • total integer

    Total after discount

  • application_fee integer

    The fee in cents that will be applied to the invoice and transferred to the application owner’s Stripe account when the invoice is paid.

  • charge string

    ID of the latest charge generated for this invoice, if any.

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

  • metadata metadata hash

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

  • next_payment_attempt timestamp

    The time at which payment will next be attempted.

  • receipt_number string

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

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

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

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

{
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
#<Stripe::Invoice id=in_16VYnk2eZvKYlo2CYnLYeOkF 0x00000a> JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
<Invoice invoice id=in_16VYnk2eZvKYlo2CYnLYeOkF at 0x00000a> JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
Stripe\Invoice JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
com.stripe.model.Invoice JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
{
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
&stripe.Invoice JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}

The invoice_line_item object

Attributes
  • id string

    The ID of the source of this line item, either an invoice item or a subscription

  • object string

    line_item

  • livemode boolean

    Whether or not this is a test line item

  • amount integer

    The amount, in cents

  • currency currency

  • discountable boolean

    If true, discounts will apply to this line item. Always false for prorations.

  • metadata metadata hash

    Key-value pairs attached to the line item, if the line item is an 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.

  • proration boolean

    Whether or not this is a proration

  • type string

    A string identifying the type of the source of this line item, either an invoiceitem or a subscription

  • description string

    A text description of the line item, if the line item is an invoice item

  • plan hash, plan object

    The plan of the subscription, if the line item is a subscription or 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.

{
  "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": -100,
  "currency": "usd",
  "proration": true,
  "period": {
    "start": 1438466217,
    "end": 1438466217
  },
  "subscription": "sub_6iZ6BxaCYMA4Ai",
  "quantity": 1,
  "plan": {
    "interval": "week",
    "name": "Foo",
    "created": 1438466211,
    "amount": 100,
    "currency": "usd",
    "id": "30118foo1438466209",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "description": "Unused time on Foo after 01 Aug 2015",
  "discountable": false,
  "metadata": {
  }
}
#<Stripe::LineItem id=ii_16V7yP2eZvKYlo2CxN0t7z7V 0x00000a> JSON: {
  "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": -100,
  "currency": "usd",
  "proration": true,
  "period": {
    "start": 1438466217,
    "end": 1438466217
  },
  "subscription": "sub_6iZ6BxaCYMA4Ai",
  "quantity": 1,
  "plan": {
    "interval": "week",
    "name": "Foo",
    "created": 1438466211,
    "amount": 100,
    "currency": "usd",
    "id": "30118foo1438466209",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "description": "Unused time on Foo after 01 Aug 2015",
  "discountable": false,
  "metadata": {
  }
}
<LineItem line_item id=ii_16V7yP2eZvKYlo2CxN0t7z7V at 0x00000a> JSON: {
  "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": -100,
  "currency": "usd",
  "proration": true,
  "period": {
    "start": 1438466217,
    "end": 1438466217
  },
  "subscription": "sub_6iZ6BxaCYMA4Ai",
  "quantity": 1,
  "plan": {
    "interval": "week",
    "name": "Foo",
    "created": 1438466211,
    "amount": 100,
    "currency": "usd",
    "id": "30118foo1438466209",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "description": "Unused time on Foo after 01 Aug 2015",
  "discountable": false,
  "metadata": {
  }
}
Stripe\LineItem JSON: {
  "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": -100,
  "currency": "usd",
  "proration": true,
  "period": {
    "start": 1438466217,
    "end": 1438466217
  },
  "subscription": "sub_6iZ6BxaCYMA4Ai",
  "quantity": 1,
  "plan": {
    "interval": "week",
    "name": "Foo",
    "created": 1438466211,
    "amount": 100,
    "currency": "usd",
    "id": "30118foo1438466209",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "description": "Unused time on Foo after 01 Aug 2015",
  "discountable": false,
  "metadata": {
  }
}
com.stripe.model.LineItem JSON: {
  "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": -100,
  "currency": "usd",
  "proration": true,
  "period": {
    "start": 1438466217,
    "end": 1438466217
  },
  "subscription": "sub_6iZ6BxaCYMA4Ai",
  "quantity": 1,
  "plan": {
    "interval": "week",
    "name": "Foo",
    "created": 1438466211,
    "amount": 100,
    "currency": "usd",
    "id": "30118foo1438466209",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "description": "Unused time on Foo after 01 Aug 2015",
  "discountable": false,
  "metadata": {
  }
}
{
  "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": -100,
  "currency": "usd",
  "proration": true,
  "period": {
    "start": 1438466217,
    "end": 1438466217
  },
  "subscription": "sub_6iZ6BxaCYMA4Ai",
  "quantity": 1,
  "plan": {
    "interval": "week",
    "name": "Foo",
    "created": 1438466211,
    "amount": 100,
    "currency": "usd",
    "id": "30118foo1438466209",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "description": "Unused time on Foo after 01 Aug 2015",
  "discountable": false,
  "metadata": {
  }
}
&stripe.LineItem JSON: {
  "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": -100,
  "currency": "usd",
  "proration": true,
  "period": {
    "start": 1438466217,
    "end": 1438466217
  },
  "subscription": "sub_6iZ6BxaCYMA4Ai",
  "quantity": 1,
  "plan": {
    "interval": "week",
    "name": "Foo",
    "created": 1438466211,
    "amount": 100,
    "currency": "usd",
    "id": "30118foo1438466209",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "description": "Unused time on Foo after 01 Aug 2015",
  "discountable": false,
  "metadata": {
  }
}

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_6iyQXxYdktOlra
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Invoice.create(
    :customer => "cus_6iyQXxYdktOlra"
)
import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.create(
    customer="cus_6iyQXxYdktOlra"
)
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Invoice::create(array(
    "customer" => "cus_6iyQXxYdktOlra"
));
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> invoiceParams = new HashMap<String, Object>();
invoiceParams.put("customer", "cus_6iyQXxYdktOlra");

Invoice.create(invoiceParams);
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoices.create({
  customer: "cus_6iyQXxYdktOlra"
}, function(err, invoice) {
  // asynchronously called
});
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

i, err := invoice.New(&stripe.InvoiceParams{Customer: "cus_6iyQXxYdktOlra"})
{
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": true,
        "period": {
          "start": 1438466217,
          "end": 1438466217
        },
        "subscription": "sub_6iZ6BxaCYMA4Ai",
        "quantity": 1,
        "plan": {
          "interval": "week",
          "name": "Foo",
          "created": 1438466211,
          "amount": 100,
          "currency": "usd",
          "id": "30118foo1438466209",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": "Unused time on Foo after 01 Aug 2015",
        "discountable": false,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
#<Stripe::Invoice id=in_16VYnk2eZvKYlo2CYnLYeOkF 0x00000a> JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": true,
        "period": {
          "start": 1438466217,
          "end": 1438466217
        },
        "subscription": "sub_6iZ6BxaCYMA4Ai",
        "quantity": 1,
        "plan": {
          "interval": "week",
          "name": "Foo",
          "created": 1438466211,
          "amount": 100,
          "currency": "usd",
          "id": "30118foo1438466209",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": "Unused time on Foo after 01 Aug 2015",
        "discountable": false,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
<Invoice invoice id=in_16VYnk2eZvKYlo2CYnLYeOkF at 0x00000a> JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": true,
        "period": {
          "start": 1438466217,
          "end": 1438466217
        },
        "subscription": "sub_6iZ6BxaCYMA4Ai",
        "quantity": 1,
        "plan": {
          "interval": "week",
          "name": "Foo",
          "created": 1438466211,
          "amount": 100,
          "currency": "usd",
          "id": "30118foo1438466209",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": "Unused time on Foo after 01 Aug 2015",
        "discountable": false,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
Stripe\Invoice JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": true,
        "period": {
          "start": 1438466217,
          "end": 1438466217
        },
        "subscription": "sub_6iZ6BxaCYMA4Ai",
        "quantity": 1,
        "plan": {
          "interval": "week",
          "name": "Foo",
          "created": 1438466211,
          "amount": 100,
          "currency": "usd",
          "id": "30118foo1438466209",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": "Unused time on Foo after 01 Aug 2015",
        "discountable": false,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
com.stripe.model.Invoice JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": true,
        "period": {
          "start": 1438466217,
          "end": 1438466217
        },
        "subscription": "sub_6iZ6BxaCYMA4Ai",
        "quantity": 1,
        "plan": {
          "interval": "week",
          "name": "Foo",
          "created": 1438466211,
          "amount": 100,
          "currency": "usd",
          "id": "30118foo1438466209",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": "Unused time on Foo after 01 Aug 2015",
        "discountable": false,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
{
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": true,
        "period": {
          "start": 1438466217,
          "end": 1438466217
        },
        "subscription": "sub_6iZ6BxaCYMA4Ai",
        "quantity": 1,
        "plan": {
          "interval": "week",
          "name": "Foo",
          "created": 1438466211,
          "amount": 100,
          "currency": "usd",
          "id": "30118foo1438466209",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": "Unused time on Foo after 01 Aug 2015",
        "discountable": false,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
&stripe.Invoice JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "ii_16V7yP2eZvKYlo2CxN0t7z7V",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": true,
        "period": {
          "start": 1438466217,
          "end": 1438466217
        },
        "subscription": "sub_6iZ6BxaCYMA4Ai",
        "quantity": 1,
        "plan": {
          "interval": "week",
          "name": "Foo",
          "created": 1438466211,
          "amount": 100,
          "currency": "usd",
          "id": "30118foo1438466209",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": "Unused time on Foo after 01 Aug 2015",
        "discountable": false,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}

Retrieve an invoice

Retrieves the invoice with the given ID.

Arguments
  • id required

    The identifier of the desired invoice.

Returns

Returns an invoice object if a valid invoice ID was provided. 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 null.

curl https://api.stripe.com/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

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

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

Invoice.retrieve("in_16VYnk2eZvKYlo2CYnLYeOkF");
var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

i, err := invoice.Get("in_16VYnk2eZvKYlo2CYnLYeOkF", nil)
{
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
#<Stripe::Invoice id=in_16VYnk2eZvKYlo2CYnLYeOkF 0x00000a> JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
<Invoice invoice id=in_16VYnk2eZvKYlo2CYnLYeOkF at 0x00000a> JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  "attempted": false,
  "closed": false,
  "forgiven": false,
  "paid": false,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": 1438572944,
  "webhooks_delivered_at": 1438569347,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_4KfFIGykKDcoUl",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}
Stripe\Invoice JSON: {
  "date": 1438569344,
  "id": "in_16VYnk2eZvKYlo2CYnLYeOkF",
  "period_start": 1435890364,
  "period_end": 1438568764,
  "lines": {
    "data": [
      {
        "id": "sub_6j0qn6K5MouxnK",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1441247786,
          "end": 1443839786
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "discountable": true,
        "metadata": {
        }
      }
    ],
    "total_count": 1,
    "object": "list",
    "url": "/v1/invoices/in_16VYnk2eZvKYlo2CYnLYeOkF/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_6iyQXxYdktOlra",
  "object": "invoice",
  &qu