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 one of your API keys in the request. You can manage your API keys from your account. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!

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

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

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

To use your API key, you need only call \Stripe\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

incorrect_number	The card number is incorrect.
invalid_number	The card number is not a valid credit card number.
invalid_expiry_month	The card's expiration month is invalid.
invalid_expiry_year	The card's expiration year is invalid.
invalid_cvc	The card's security code is invalid.
expired_card	The card has expired.
incorrect_cvc	The card's security code is incorrect.
incorrect_zip	The card's zip code failed validation.
card_declined	The card was declined.
missing	There is no card on a customer that is being charged.
processing_error	An error occurred while processing the card.
rate_limit	An error occurred due to requests hitting the API too quickly. Please let us know if you're consistently running into this error.

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
endtry:
  # Use Stripe's bindings...
  pass
except stripe.error.CardError, e:
  # Since it's a decline, stripe.error.CardError will be caught
  body = e.json_body
  err  = body['error']

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

switch (err.type) {
  case 'StripeCardError':
    // A declined card error
    err.message; // => e.g. "Your card's expiration year is invalid."
    break;
  case 'StripeInvalidRequestError':
    // Invalid parameters were supplied to Stripe's API
    break;
  case 'StripeAPIError':
    // An error occurred internally with Stripe's API
    break;
  case 'StripeConnectionError':
    // Some kind of error occurred during the HTTPS communication
    break;
  case 'StripeAuthenticationError':
    // You probably used an incorrect API key
    break;
}_, err := // Go bindings call

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

  switch stripeErr.Type {
  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 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.
data array

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

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

The URL where this list can be accessed.

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

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.all

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.all()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::all();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer.all(new HashMap<String, Object>());

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.list({ 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": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    },
    {...},
    {...}
  ]
}

#<Stripe::ListObject:0x3fe634d74498&gt JSON: {
  "object": "list",
  "url": "v1/customers",
  "has_more": false,
  "data": [
    #<Stripe::Customer id=cus_5oWwNidx34nxOf 0x00000a> JSON: {
      "object": "customer",
      "created": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    },
    #<Stripe::Customer[...] ...>,
    #<Stripe::Customer[...] ...>
  ]
}

{
  object: "list",
  url: "v1/customers",
  has_more: false,
  data: [
    <Customer customer  id=cus_5oWwNidx34nxOf at 0x00000a> JSON: {
      "object": "customer",
      "created": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    },
    <stripe.Customer[...] ...>,
    <stripe.Customer[...] ...>
  ]
}

Stripe\Collection JSON: {
  "object" => "list",
  "url" => "v1/customers",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Customer JSON: {
      "object": "customer",
      "created": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    }
    [1] => <Stripe\Customer[...] ...>
    [2] => <Stripe\Customer[...] ...>
  ]
}

#<com.stripe.model.CustomerCollection id=#> JSON: {
  "data": [
    com.stripe.model.Customer JSON: {
      "object": "customer",
      "created": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    },
    #<com.stripe.model.Customer[...] ...>,
    #<com.stripe.model.Customer[...] ...>
  ],
  "has_more": false
}

{
  "object": "list",
  "url": "v1/customers",
  "has_more": false,
  "data": [
    {
      "object": "customer",
      "created": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    },
    {...},
    {...}
  ]
}

&stripe.Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

Versioning

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

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-02-18"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
Stripe.api_version = "2015-02-18"

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
stripe.api_version = '2015-02-18'

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
\Stripe\Stripe::setApiVersion("2015-02-18");

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
Stripe.apiVersion = "2015-02-18";

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);
stripe.setApiVersion('2015-02-18');

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_15ctsW2eZvKYlo2CAb7RTMhn \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d expand[]=customer

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.retrieve(:id => "ch_15ctsW2eZvKYlo2CAb7RTMhn", :expand => ['customer'])

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn", expand=['customer'])

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::retrieve(array("id" => "ch_15ctsW2eZvKYlo2CAb7RTMhn", "expand" => array("customer")));

The Stripe Java library does not support this feature.

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn", {
  expand: ["customer"]
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ChargeParams{}
params.Expand("customer")
charge.Get("ch_15ctsW2eZvKYlo2CAb7RTMhn", 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_15cOky2eZvKYlo2CJpXkqmIV \
   -d metadata[order_id]=6735

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.ChargeParams{
  Amount: 400,
  Currency: "usd",
}
params.SetSource("tok_15cOky2eZvKYlo2CJpXkqmIV") // obtained with Stripe.js
params.AddMeta("order_id", "6735")
charge.New(params)

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

#<Stripe::Charge id=ch_15ctsW2eZvKYlo2CAb7RTMhn 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

<Charge charge  id=ch_15ctsW2eZvKYlo2CAb7RTMhn at 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

Stripe\Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

com.stripe.model.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

&stripe.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/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 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: z5XznVeXHvijsGr9" \
   -d amount=400 \
   -d source=tok_15cOky2eZvKYlo2CJpXkqmIV \
   -d currency=usd

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.create({
  :amount => 400,
  :currency => "usd",
  :source => "tok_15cOky2eZvKYlo2CJpXkqmIV", # obtained with Stripe.js
  :description => "Charge for test@example.com"
}, {
  :idempotency_key => "z5XznVeXHvijsGr9"
})

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.create(
  amount=400,
  currency="usd",
  source="tok_15cOky2eZvKYlo2CJpXkqmIV", # obtained with Stripe.js
  idempotency_key='z5XznVeXHvijsGr9'
)

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

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_15cOky2eZvKYlo2CJpXkqmIV"); // obtained with Stripe.js
chargeParams.put("description", "Charge for test@example.com");

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

Charge.create(chargeParams, options);

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

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
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.
paid boolean
refunded boolean

Whether or not the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
refunds 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 refunded, in cents.
  - created timestamp
  - currency currency
    
    Three-letter ISO code representing the currency of the refund.
  - balance_transaction string
    
    Balance transaction that describes the impact of this refund on your account balance.
  - charge string
    
    ID of the charge that was refunded.
  - metadata metadata hash
    
    A set of key/value pairs that you can attach to a refund. It can be useful for storing additional information about the refund in a structured format.
  - reason string
    
    Reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer.
  - receipt_number string
    
    This is the transaction number that appears on email receipts sent for this refund.
  - description string
- 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.
amount_refunded positive integer or zero

Amount in cents refunded (can be less than the amount attribute on the charge if a partial refund was issued).
balance_transaction 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
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.
invoice string

ID of the invoice this charge is for if one exists.
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.
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.
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.
shipping hash or null

Shipping information for the charge.
child attributes
- address hash
  
  Shipping address.
  child attributes
  - line1 string
    
    Address line 1 (Street address/PO Box/Company name)
  - city string
    
    City/Suburb/Town/Village
  - country string
    
    2-letter country code
  - line2 string
    
    Address line 2 (Apartment/Suite/Unit/Building)
  - postal_code string
    
    Zip/Postal Code
  - state string
    
    State/Province/County
- 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.

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}#<Stripe::Charge id=ch_15ctsW2eZvKYlo2CAb7RTMhn 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}<Charge charge  id=ch_15ctsW2eZvKYlo2CAb7RTMhn at 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}Stripe\Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}com.stripe.model.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}&stripe.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/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 card won't actually be charged, though everything else will occur as if in live mode. (Stripe assumes that the charge would have completed successfully).

Arguments

amount required

A positive integer in the smallest currency unit (e.g 100 cents to charge $1.00, or 1 to charge ¥1, a 0-decimal currency) representing how much to charge the card. The minimum amount is $0.50 (or equivalent in charge currency).
currency required

3-letter ISO code for currency.
customer optional, either customer or 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.
application_fee optional

A fee in cents that will be applied to the charge and transferred to the application owner's Stripe account. The request must be made with an OAuth key in order to take an application fee. For more information, see the application fees documentation.
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_15cOky2eZvKYlo2CJpXkqmIV \
   -d description="Charge for test@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.create(
  :amount => 400,
  :currency => "usd",
  :source => "tok_15cOky2eZvKYlo2CJpXkqmIV", # 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_15cOky2eZvKYlo2CJpXkqmIV", # 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_15cOky2eZvKYlo2CJpXkqmIV", // 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_15cOky2eZvKYlo2CJpXkqmIV"); // 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_15cOky2eZvKYlo2CJpXkqmIV", // 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_15cOky2eZvKYlo2CJpXkqmIV")
ch, err := charge.New(chargeParams)

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

#<Stripe::Charge id=ch_15ctsW2eZvKYlo2CAb7RTMhn 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

<Charge charge  id=ch_15ctsW2eZvKYlo2CAb7RTMhn at 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

Stripe\Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

com.stripe.model.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

&stripe.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

Verification reponses

CVC card[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 card[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 card[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.

GET https://api.stripe.com/v1/charges/{CHARGE_ID}

Stripe::Charge.retrieve({CHARGE_ID})

stripe.Charge.retrieve({CHARGE_ID})

\Stripe\Charge::retrieve({CHARGE_ID});

Charge.retrieve({CHARGE_ID});

stripe.charges.retrieve({CHARGE_ID});

charge.Get({CHARGE_ID})

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

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn");

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn");

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.retrieve(
  "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  function(err, charge) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch, err := charge.Get("ch_15ctsW2eZvKYlo2CAb7RTMhn", nil)

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

#<Stripe::Charge id=ch_15ctsW2eZvKYlo2CAb7RTMhn 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

<Charge charge  id=ch_15ctsW2eZvKYlo2CAb7RTMhn at 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

Stripe\Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

com.stripe.model.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

&stripe.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/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.

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_15ctsW2eZvKYlo2CAb7RTMhn \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Charge for test@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn")
ch.description = "Charge for test@example.com"
ch.save

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn")
ch.description = "Charge for test@example.com"
ch.save()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch, err := charge.Update(
  "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  &stripe.ChargeParams{Desc: "Charge for test@example.com"}
)

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

#<Stripe::Charge id=ch_15ctsW2eZvKYlo2CAb7RTMhn 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

<Charge charge  id=ch_15ctsW2eZvKYlo2CAb7RTMhn at 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

Stripe\Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

com.stripe.model.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

&stripe.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/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.

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_15ctsW2eZvKYlo2CAb7RTMhn/capture \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn")
ch.capture

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn")
ch.capture()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = \Stripe\Charge::retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn");
$ch->capture();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

ch = Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn");
ch.capture();

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.capture("ch_15ctsW2eZvKYlo2CAb7RTMhn", function(err, charge) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch, err := charge.Capture("ch_15ctsW2eZvKYlo2CAb7RTMhn", nil)

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

#<Stripe::Charge id=ch_15ctsW2eZvKYlo2CAb7RTMhn 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

<Charge charge  id=ch_15ctsW2eZvKYlo2CAb7RTMhn at 0x00000a> JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": "True",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

Stripe\Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

com.stripe.model.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": "true",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

{
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": "true",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
    "data": [

    ]
  }
}

&stripe.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": "true",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/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

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 dictionaryhashdictionaryassociative arrayMapobjectmap with the following options:
child arguments
- gtgtgtgtgtgtgt optional
  
  Return values where the created field is after this timestamp.
- gtegtegtegtegtegtegte optional
  
  Return values where the created field is after or equal to this timestamp.
- ltltltltltltlt optional
  
  Return values where the created field is before this timestamp.
- lteltelteltelteltelte 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() {
  ch := i.Charge()
}

{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
      "object": "charge",
      "created": 1425542324,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 25000,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      },
      "captured": true,
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": "cus_5oWwNidx34nxOf",
      "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
        "data": [
    
        ]
      }
    },
    {...},
    {...}
  ]
}

#<Stripe::ListObject:0x3fe634d74498&gt JSON: {
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    #<Stripe::Charge id=ch_15ctsW2eZvKYlo2CAb7RTMhn 0x00000a> JSON: {
      "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
      "object": "charge",
      "created": 1425542324,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 25000,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      },
      "captured": true,
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": "cus_5oWwNidx34nxOf",
      "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
        "data": [
    
        ]
      }
    },
    #<Stripe::Charge[...] ...>,
    #<Stripe::Charge[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/charges",
  has_more: false,
  data: [
    <Charge charge  id=ch_15ctsW2eZvKYlo2CAb7RTMhn at 0x00000a> JSON: {
      "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
      "object": "charge",
      "created": 1425542324,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 25000,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      },
      "captured": true,
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": "cus_5oWwNidx34nxOf",
      "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
        "data": [
    
        ]
      }
    },
    <stripe.Charge[...] ...>,
    <stripe.Charge[...] ...>
  ]
}

Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/charges",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Charge JSON: {
      "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
      "object": "charge",
      "created": 1425542324,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 25000,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      },
      "captured": true,
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": "cus_5oWwNidx34nxOf",
      "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
        "data": [
    
        ]
      }
    }
    [1] => <Stripe\Charge[...] ...>
    [2] => <Stripe\Charge[...] ...>
  ]
}

#<com.stripe.model.ChargeCollection id=#> JSON: {
  "data": [
    com.stripe.model.Charge JSON: {
      "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
      "object": "charge",
      "created": 1425542324,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 25000,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      },
      "captured": true,
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": "cus_5oWwNidx34nxOf",
      "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
        "data": [
    
        ]
      }
    },
    #<com.stripe.model.Charge[...] ...>,
    #<com.stripe.model.Charge[...] ...>
  ],
  "has_more": false
}

{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
      "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
      "object": "charge",
      "created": 1425542324,
      "livemode": false,
      "paid": true,
      "status": "succeeded",
      "amount": 25000,
      "currency": "usd",
      "refunded": false,
      "source": {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      },
      "captured": true,
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "failure_message": null,
      "failure_code": null,
      "amount_refunded": 0,
      "customer": "cus_5oWwNidx34nxOf",
      "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
      "description": null,
      "dispute": null,
      "metadata": {
      },
      "statement_descriptor": null,
      "fraud_details": {
      },
      "receipt_email": null,
      "receipt_number": null,
      "shipping": null,
      "refunds": {
        "object": "list",
        "total_count": 0,
        "has_more": false,
        "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/refunds",
        "data": [
    
        ]
      }
    },
    {...},
    {...}
  ]
}

&stripe.Charge JSON: {
  "id": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "object": "charge",
  "created": 1425542324,
  "livemode": false,
  "paid": true,
  "status": "succeeded",
  "amount": 25000,
  "currency": "usd",
  "refunded": false,
  "source": {
    "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "funding": "credit",
    "exp_month": 10,
    "exp_year": 2016,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "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,
    "dynamic_last4": null,
    "metadata": {
    },
    "customer": "cus_5oWwNidx34nxOf"
  },
  "captured": true,
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": "cus_5oWwNidx34nxOf",
  "invoice": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "fraud_details": {
  },
  "receipt_email": null,
  "receipt_number": null,
  "shipping": null,
  "refunds": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/charges/ch_15ctsW2eZvKYlo2CAb7RTMhn/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 refunded, in cents.
created timestamp
currency currency

Three-letter ISO code representing the currency of the refund.
balance_transaction string

Balance transaction that describes the impact of this refund on your account balance.
charge string

ID of the charge that was refunded.
metadata metadata hash

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

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

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

{
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}#<Stripe::Refund id=re_15cswN2eZvKYlo2CVCDoH5Gk 0x00000a> JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}<Refund refund  id=re_15cswN2eZvKYlo2CVCDoH5Gk at 0x00000a> JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}Stripe\Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}com.stripe.model.Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}{
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}&stripe.Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": null,
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "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

id required

The identifier of the charge to be refunded.
amount optional, default is entire charge

A positive integer in cents representing how much of this charge to refund. Can only refund up to the unrefunded amount remaining of the charge.
refund_application_fee optional, 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.
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_15ctsW2eZvKYlo2CAb7RTMhn/refunds \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POST

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn")
refund = ch.refunds.create

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn")
re = ch.refunds.create()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = \Stripe\Charge::retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn");
$re = $ch->refunds->create();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> params = new HashMap<String, Object>();
Charge ch = Charge.retrieve("ch_15ctsW2eZvKYlo2CAb7RTMhn");
Refund re = ch.getRefunds().create(params);

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.createRefund(
  "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  { },
  function(err, refund) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

r, err := refund.New(&stripe.RefundParams{Charge: "ch_15ctsW2eZvKYlo2CAb7RTMhn"})

{
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

#<Stripe::Refund id=re_15cswN2eZvKYlo2CVCDoH5Gk 0x00000a> JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

<Refund refund  id=re_15cswN2eZvKYlo2CVCDoH5Gk at 0x00000a> JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

Stripe\Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

com.stripe.model.Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

{
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

&stripe.Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "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.

GET https://api.stripe.com/v1/charges/{CHARGE_ID}/refunds/{REFUND_ID}

charge = Stripe::Charge.retrieve({CHARGE_ID})
refund = charge.refunds.retrieve({REFUND_ID})

charge = stripe.Charge.retrieve({CHARGE_ID})
refund = charge.refunds.retrieve({REFUND_ID})

$charge = \Stripe\Charge::retrieve({CHARGE_ID});
$refund = $charge->refunds->retrieve({REFUND_ID}));

Charge cu = Charge.retrieve({CHARGE_ID});
Refund re = cu.getRefunds().retrieve({REFUND_ID});

stripe.charge.retrieveRefund(
  {CHARGE_ID},
  {REFUND_ID},
  function(refund) {...}
);

refund.Get({REFUND_ID}, &stripe.RefundParams{Charge: {CHARGE_ID}})

curl https://api.stripe.com/v1/charges/ch_15aLbW2eZvKYlo2CRLzaGsPA/refunds/re_15cswN2eZvKYlo2CVCDoH5Gk \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve('ch_15aLbW2eZvKYlo2CRLzaGsPA')
refund = ch.refunds.retrieve('re_15cswN2eZvKYlo2CVCDoH5Gk')

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = stripe.Charge.retrieve("ch_15aLbW2eZvKYlo2CRLzaGsPA")
refund = charge.refunds.retrieve("re_15cswN2eZvKYlo2CVCDoH5Gk")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = \Stripe\Charge::retrieve("ch_15aLbW2eZvKYlo2CRLzaGsPA");
$refund = $ch->refunds->retrieve("re_15cswN2eZvKYlo2CVCDoH5Gk");

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge ch = Charge.retrieve("ch_15aLbW2eZvKYlo2CRLzaGsPA");
Refund re = ch.getRefunds().retrieve("re_15cswN2eZvKYlo2CVCDoH5Gk");

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.retrieveRefund(
  "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "re_15cswN2eZvKYlo2CVCDoH5Gk",
  function(err, refund) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ref, err := refund.Get("re_15cswN2eZvKYlo2CVCDoH5Gk", &stripe.RefundParams{Charge: "ch_15aLbW2eZvKYlo2CRLzaGsPA"})

{
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

#<Stripe::Refund id=re_15cswN2eZvKYlo2CVCDoH5Gk 0x00000a> JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

<Refund refund  id=re_15cswN2eZvKYlo2CVCDoH5Gk at 0x00000a> JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

Stripe\Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

com.stripe.model.Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

{
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

&stripe.Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "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_15aLbW2eZvKYlo2CRLzaGsPA/refunds/re_15cswN2eZvKYlo2CVCDoH5Gk \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_15aLbW2eZvKYlo2CRLzaGsPA")
re = ch.refunds.retrieve("re_15cswN2eZvKYlo2CVCDoH5Gk")
re.metadata["key"] = "value"
re.save

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_15aLbW2eZvKYlo2CRLzaGsPA")
re = ch.refunds.retrieve("re_15cswN2eZvKYlo2CVCDoH5Gk")
re.metadata["key"] = "value"
re.save()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = \Stripe\Charge::retrieve("ch_15aLbW2eZvKYlo2CRLzaGsPA");
$re = $ch->refunds->retrieve("re_15cswN2eZvKYlo2CVCDoH5Gk");
$re->metadata["key"] = "value";
$re->save();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge ch = Charge.retrieve("ch_15aLbW2eZvKYlo2CRLzaGsPA");
Refund re = ch.getRefunds().retrieve("re_15cswN2eZvKYlo2CVCDoH5Gk");
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_15aLbW2eZvKYlo2CRLzaGsPA",
  "re_15cswN2eZvKYlo2CVCDoH5Gk",
  { metadata: { key: "value"} },
  function(err, refund) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ref, err := refund.Update(
  "re_15cswN2eZvKYlo2CVCDoH5Gk",
  &stripe.RefundParams{
    Charge: "ch_15aLbW2eZvKYlo2CRLzaGsPA",
    Meta: map[string]string{ "key": "value" }
  })

{
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
    "key": "value"
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

#<Stripe::Refund id=re_15cswN2eZvKYlo2CVCDoH5Gk 0x00000a> JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
    "key": "value"
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

<Refund refund  id=re_15cswN2eZvKYlo2CVCDoH5Gk at 0x00000a> JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
    "key": "value"
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

Stripe\Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
    "key": "value"
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

com.stripe.model.Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
    "key": "value"
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

{
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
    "key": "value"
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "receipt_number": null,
  "reason": null
}

&stripe.Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
    "key": "value"
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "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});

refund.List(&stripe.RefundListParams{Charge: {CHARGE_ID})

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

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.retrieve('ch_15aLbW2eZvKYlo2CRLzaGsPA').refunds.all(:limit => 3)

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.retrieve("ch_15aLbW2eZvKYlo2CRLzaGsPA").refunds.all(
  limit=3)

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Charge::retrieve("ch_15aLbW2eZvKYlo2CRLzaGsPA")
  ->refunds->all(array('limit'=>3));

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge ch = Charge.retrieve("ch_15aLbW2eZvKYlo2CRLzaGsPA");
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_15aLbW2eZvKYlo2CRLzaGsPA', function(err, refunds) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.RefundListParams{Charge: "ch_15aLbW2eZvKYlo2CRLzaGsPA"}
params.Filters.AddFilter("limit", "", "3")
i := refund.List(params)
for i.Next() {
  ref := i.Refund()
}

{
  "object": "list",
  "url": "/v1/charges/ch_15aLbW2eZvKYlo2CRLzaGsPA/refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
      "amount": 50,
      "currency": "usd",
      "created": 1425538719,
      "object": "refund",
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "metadata": {
      },
      "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
      "receipt_number": null,
      "reason": null
    },
    {...},
    {...}
  ]
}

#<Stripe::ListObject:0x3fe634d74498&gt JSON: {
  "object": "list",
  "url": "/v1/charges/ch_15aLbW2eZvKYlo2CRLzaGsPA/refunds",
  "has_more": false,
  "data": [
    #<Stripe::Refund id=re_15cswN2eZvKYlo2CVCDoH5Gk 0x00000a> JSON: {
      "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
      "amount": 50,
      "currency": "usd",
      "created": 1425538719,
      "object": "refund",
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "metadata": {
      },
      "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
      "receipt_number": null,
      "reason": null
    },
    #<Stripe::Refund[...] ...>,
    #<Stripe::Refund[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/charges/ch_15aLbW2eZvKYlo2CRLzaGsPA/refunds",
  has_more: false,
  data: [
    <Refund refund  id=re_15cswN2eZvKYlo2CVCDoH5Gk at 0x00000a> JSON: {
      "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
      "amount": 50,
      "currency": "usd",
      "created": 1425538719,
      "object": "refund",
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "metadata": {
      },
      "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
      "receipt_number": null,
      "reason": null
    },
    <stripe.Refund[...] ...>,
    <stripe.Refund[...] ...>
  ]
}

Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/charges/ch_15aLbW2eZvKYlo2CRLzaGsPA/refunds",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Refund JSON: {
      "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
      "amount": 50,
      "currency": "usd",
      "created": 1425538719,
      "object": "refund",
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "metadata": {
      },
      "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
      "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_15cswN2eZvKYlo2CVCDoH5Gk",
      "amount": 50,
      "currency": "usd",
      "created": 1425538719,
      "object": "refund",
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "metadata": {
      },
      "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
      "receipt_number": null,
      "reason": null
    },
    #<com.stripe.model.Refund[...] ...>,
    #<com.stripe.model.Refund[...] ...>
  ],
  "has_more": false
}

{
  "object": "list",
  "url": "/v1/charges/ch_15aLbW2eZvKYlo2CRLzaGsPA/refunds",
  "has_more": false,
  "data": [
    {
      "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
      "amount": 50,
      "currency": "usd",
      "created": 1425538719,
      "object": "refund",
      "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
      "metadata": {
      },
      "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
      "receipt_number": null,
      "reason": null
    },
    {...},
    {...}
  ]
}

&stripe.Refund JSON: {
  "id": "re_15cswN2eZvKYlo2CVCDoH5Gk",
  "amount": 50,
  "currency": "usd",
  "created": 1425538719,
  "object": "refund",
  "balance_transaction": "txn_15ae562eZvKYlo2CWXVFrpPl",
  "metadata": {
  },
  "charge": "ch_15aLbW2eZvKYlo2CRLzaGsPA",
  "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
created timestamp
account_balance integer

Current balance, if any, being stored on the customer’s account. If negative, the customer has credit to apply to the next invoice. If positive, the customer has an amount owed that will be added to the next invoice. The balance does not refer to any unpaid invoices; it solely takes into account amounts that have yet to be successfully applied to any invoice. This balance is only taken into account for recurring charges.
currency string

The currency the customer can be charged in for recurring billing purposes (subscriptions, invoices, invoice items).
default_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
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
child arguments
- objectobjectobjectobjectobjectobjectobject string, value is "list"
- datadatadatadatadatadatadata list
  
  The list contains all payment sources that have been attached to the customer. These may be Cards or BitcoinReceivers.
- has_morehas_morehas_morehas_morehas_morehas_morehas_more boolean
- urlurlurlurlurlurlurl string
- total_counttotal_counttotal_counttotal_counttotal_counttotal_counttotal_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

{
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}#<Stripe::Customer id=cus_5oWwNidx34nxOf 0x00000a> JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}<Customer customer  id=cus_5oWwNidx34nxOf at 0x00000a> JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}Stripe\Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}com.stripe.model.Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}{
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}&stripe.Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

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
child arguments
- 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
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 a non-free plan is specified and a source is not provided (unless the plan has a trial period), 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_15cOky2eZvKYlo2CJpXkqmIV

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.create(
  :description => "Customer for test@example.com",
  :source => "tok_15cOky2eZvKYlo2CJpXkqmIV" # obtained with Stripe.js
)

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.create(
  description="Customer for test@example.com",
  source="tok_15cOky2eZvKYlo2CJpXkqmIV" # obtained with Stripe.js
)

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

{
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

#<Stripe::Customer id=cus_5oWwNidx34nxOf 0x00000a> JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

<Customer customer  id=cus_5oWwNidx34nxOf at 0x00000a> JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

Stripe\Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

com.stripe.model.Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

{
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

&stripe.Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

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.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}

Stripe::Customer.retrieve({CUSTOMER_ID})

stripe.Customer.retrieve({CUSTOMER_ID})

\Stripe\Customer::retrieve({CUSTOMER_ID});

Customer.retrieve({CUSTOMER_ID});

stripe.customers.retrieve({CUSTOMER_ID});

customer.Get({CUSTOMER_ID})

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

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.retrieve("cus_5oWwNidx34nxOf")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer.retrieve("cus_5oWwNidx34nxOf");

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.retrieve("cus_5oWwNidx34nxOf", function(err, customer) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := customer.Get("cus_5oWwNidx34nxOf", nil)

{
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

#<Stripe::Customer id=cus_5oWwNidx34nxOf 0x00000a> JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

<Customer customer  id=cus_5oWwNidx34nxOf at 0x00000a> JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

Stripe\Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

com.stripe.model.Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

{
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

&stripe.Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

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 card parameter, that becomes the customer's active card to be used for all charges in the future. When you update a customer to a new valid card: 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 card.)

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.
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
child arguments
- 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

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

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}

cu = Stripe::Customer.retrieve({CUSTOMER_ID})
cu.description = {NEW_DESCRIPTION}
...
cu.save

cu = stripe.Customer.retrieve({CUSTOMER_ID})
cu.description = {NEW_DESCRIPTION}
...
cu.save()

$cu = \Stripe\Customer::retrieve({CUSTOMER_ID});
$cu->description = {NEW_DESCRIPTION};
...
$cu->save();

Customer cu = Customer.retrieve({CUSTOMER_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", {NEW_DESCRIPTION});
...
cu.update(updateParams);

stripe.customers.update({CUSTOMER_ID}, {
  description: {NEW_DESCRIPTION},
  ...
});

customer.Update(
  {CUSTOMER_ID},
  &stripe.CustomerParams{
    Desc: {NEW_DESCRIPTION},
    ...
  })

curl https://api.stripe.com/v1/customers/cus_5oWwNidx34nxOf \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d description="Customer for test@example.com"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
cu.description = "Customer for test@example.com"
cu.card = "tok_15cOky2eZvKYlo2CJpXkqmIV" # obtained with Stripe.js
cu.save

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
cu.description = "Customer for test@example.com"
cu.save()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$cu->description = "Customer for test@example.com";
$cu->card = "tok_15cOky2eZvKYlo2CJpXkqmIV"; // obtained with Stripe.js
$cu->save();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := customer.Update(
      "cus_5oWwNidx34nxOf",
      &stripe.CustomerParams{Desc: "Customer for test@example.com"}
    )

{
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": "Customer for test@example.com",
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

#<Stripe::Customer id=cus_5oWwNidx34nxOf 0x00000a> JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": "Customer for test@example.com",
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

<Customer customer  id=cus_5oWwNidx34nxOf at 0x00000a> JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": "Customer for test@example.com",
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

Stripe\Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": "Customer for test@example.com",
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

com.stripe.model.Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": "Customer for test@example.com",
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

{
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": "Customer for test@example.com",
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

&stripe.Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": "Customer for test@example.com",
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

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_5oWwNidx34nxOf \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
cu.delete

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
cu.delete()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$cu->delete();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
cu.delete();

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.del(
  "cus_5oWwNidx34nxOf",
  function(err, confirmation) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := customer.Del("cus_5oWwNidx34nxOf")

{
  "deleted": true,
  "id": "cus_5oWwNidx34nxOf"
}

#<Stripe::Object id=cus_5oWwNidx34nxOf 0x00000a> JSON: {
  "deleted": true,
  "id": "cus_5oWwNidx34nxOf"
}

<Object object  id=cus_5oWwNidx34nxOf at 0x00000a> JSON: {
  "deleted": true,
  "id": "cus_5oWwNidx34nxOf"
}

Stripe\Object JSON: {
  "deleted": true,
  "id": "cus_5oWwNidx34nxOf"
}

com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "cus_5oWwNidx34nxOf"
}

{
  "deleted": true,
  "id": "cus_5oWwNidx34nxOf"
}

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

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 dictionaryhashdictionaryassociative arrayMapobjectmap with the following options:
child arguments
- gtgtgtgtgtgtgt optional
  
  Return values where the created field is after this timestamp.
- gtegtegtegtegtegtegte optional
  
  Return values where the created field is after or equal to this timestamp.
- ltltltltltltlt optional
  
  Return values where the created field is before this timestamp.
- lteltelteltelteltelte 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 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.all

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.all()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::all();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer.all(new HashMap<String, Object>());

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.list({ 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": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    },
    {...},
    {...}
  ]
}

#<Stripe::ListObject:0x3fe634d74498&gt JSON: {
  "object": "list",
  "url": "v1/customers",
  "has_more": false,
  "data": [
    #<Stripe::Customer id=cus_5oWwNidx34nxOf 0x00000a> JSON: {
      "object": "customer",
      "created": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    },
    #<Stripe::Customer[...] ...>,
    #<Stripe::Customer[...] ...>
  ]
}

{
  object: "list",
  url: "v1/customers",
  has_more: false,
  data: [
    <Customer customer  id=cus_5oWwNidx34nxOf at 0x00000a> JSON: {
      "object": "customer",
      "created": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    },
    <stripe.Customer[...] ...>,
    <stripe.Customer[...] ...>
  ]
}

Stripe\Collection JSON: {
  "object" => "list",
  "url" => "v1/customers",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Customer JSON: {
      "object": "customer",
      "created": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    }
    [1] => <Stripe\Customer[...] ...>
    [2] => <Stripe\Customer[...] ...>
  ]
}

#<com.stripe.model.CustomerCollection id=#> JSON: {
  "data": [
    com.stripe.model.Customer JSON: {
      "object": "customer",
      "created": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    },
    #<com.stripe.model.Customer[...] ...>,
    #<com.stripe.model.Customer[...] ...>
  ],
  "has_more": false
}

{
  "object": "list",
  "url": "v1/customers",
  "has_more": false,
  "data": [
    {
      "object": "customer",
      "created": 1425542324,
      "id": "cus_5oWwNidx34nxOf",
      "livemode": false,
      "description": null,
      "email": null,
      "delinquent": false,
      "metadata": {
      },
      "subscriptions": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
        "data": [
          {
            "id": "sub_5oWwPSOxF6rEpI",
            "plan": {
              "interval": "month",
              "name": "Recurring Billing",
              "created": 1398969238,
              "amount": 25000,
              "currency": "usd",
              "id": "9",
              "object": "plan",
              "livemode": false,
              "interval_count": 1,
              "trial_period_days": null,
              "metadata": {
              },
              "statement_descriptor": null
            },
            "object": "subscription",
            "start": 1425542324,
            "status": "active",
            "customer": "cus_5oWwNidx34nxOf",
            "cancel_at_period_end": false,
            "current_period_start": 1425542324,
            "current_period_end": 1428220724,
            "ended_at": null,
            "trial_start": null,
            "trial_end": null,
            "canceled_at": null,
            "quantity": 1,
            "application_fee_percent": null,
            "discount": null,
            "tax_percent": null,
            "metadata": {
            }
          }
        ]
      },
      "discount": null,
      "account_balance": 0,
      "currency": "usd",
      "sources": {
        "object": "list",
        "total_count": 1,
        "has_more": false,
        "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
        "data": [
          {
            "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
            "object": "card",
            "last4": "4242",
            "brand": "Visa",
            "funding": "credit",
            "exp_month": 10,
            "exp_year": 2016,
            "fingerprint": "Xt5EWLLDS7FJjR1c",
            "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,
            "dynamic_last4": null,
            "metadata": {
            },
            "customer": "cus_5oWwNidx34nxOf"
          }
        ]
      },
      "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
    },
    {...},
    {...}
  ]
}

&stripe.Customer JSON: {
  "object": "customer",
  "created": 1425542324,
  "id": "cus_5oWwNidx34nxOf",
  "livemode": false,
  "description": null,
  "email": null,
  "delinquent": false,
  "metadata": {
  },
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/subscriptions",
    "data": [
      {
        "id": "sub_5oWwPSOxF6rEpI",
        "plan": {
          "interval": "month",
          "name": "Recurring Billing",
          "created": 1398969238,
          "amount": 25000,
          "currency": "usd",
          "id": "9",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "object": "subscription",
        "start": 1425542324,
        "status": "active",
        "customer": "cus_5oWwNidx34nxOf",
        "cancel_at_period_end": false,
        "current_period_start": 1425542324,
        "current_period_end": 1428220724,
        "ended_at": null,
        "trial_start": null,
        "trial_end": null,
        "canceled_at": null,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null,
        "tax_percent": null,
        "metadata": {
        }
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "sources": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_5oWwNidx34nxOf/sources",
    "data": [
      {
        "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
        "object": "card",
        "last4": "4242",
        "brand": "Visa",
        "funding": "credit",
        "exp_month": 10,
        "exp_year": 2016,
        "fingerprint": "Xt5EWLLDS7FJjR1c",
        "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,
        "dynamic_last4": null,
        "metadata": {
        },
        "customer": "cus_5oWwNidx34nxOf"
      }
    ]
  },
  "default_source": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

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 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
fingerprint string

Uniquely identifies this particular card number. You can use this attribute to check whether two customers who’ve signed up with you are using the same card number, for example.
funding string

Card funding type. Can be credit, debit, prepaid, or unknown
last4 string
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.
customer string

The customer that this card belongs to. This attribute will not be in the card object if the card belongs to a recipient instead.
cvc_check string

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

(For Apple Pay integrations only.) The last four digits of the device account number.
name string

Cardholder name
recipient string

The recipient that this card belongs to. This attribute will not be in the card object if the card belongs to a customer instead.

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}#<Stripe::Card id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}<Card card  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}Stripe\Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}com.stripe.model.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}&stripe.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

Create a card

When you create a new credit card, you must specify a customer or recipient 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 or update the recipient to have a new default_card.

Arguments

source required
child arguments
- 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

Returns

Returns the card object.

Customer Recipient

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources

customer = Stripe::Customer.retrieve({CUSTOMER_ID})
customer.sources.create({:source => TOKEN_ID})

customer = stripe.Customer.retrieve({CUSTOMER_ID})
customer.sources.create(source={TOKEN_ID})

$customer = \Stripe\Customer::retrieve({CUSTOMER_ID});
$customer->sources->create(array("source" => {TOKEN_ID}));

Customer cu = Customer.retrieve({CUSTOMER_ID});
Map<String, Object> params = new HashMap<String, Object>();
params.put("card", {TOKEN_ID});
cu.createCard(params);

stripe.customers.createCard({CUSTOMER_ID}, {
  source: {TOKEN_ID}
});

card.New(&stripe.CardParams{Customer: {CUSTOMER_ID}, Token: {TOKEN_ID}})

curl https://api.stripe.com/v1/customers/cus_5oWwNidx34nxOf/sources \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d source=token_id

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
customer.sources.create(:card => "tok_15cOky2eZvKYlo2CJpXkqmIV")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
customer.sources.create(card="tok_15cOky2eZvKYlo2CJpXkqmIV")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$cu->sources->create(array("card" => "tok_15cOky2eZvKYlo2CJpXkqmIV"));

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
Map<String, Object> params = new HashMap<String, Object>();
params.put("card", "tok_15cOky2eZvKYlo2CJpXkqmIV");
cu.createCard(params)

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.createCard(
  "cus_5oWwNidx34nxOf",
  {card: "tok_15cOky2eZvKYlo2CJpXkqmIV"},
  function(err, card) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.New(&stripe.CardParams{
  Customer: "cus_5oWwNidx34nxOf",
  Token: "tok_15cOky2eZvKYlo2CJpXkqmIV",
})

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

#<Stripe::Card id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

<Card card  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

Stripe\Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

com.stripe.model.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

&stripe.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

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_15cKMe2eZvKYlo2COsPyhwbd/cards \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d card=token_id

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd")
recipient.cards.create(:card => "tok_15cOky2eZvKYlo2CJpXkqmIV")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd")
recipient.cards.create(card="tok_15cOky2eZvKYlo2CJpXkqmIV")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Recipient::retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd");
$cu->cards->create(array("card" => "tok_15cOky2eZvKYlo2CJpXkqmIV"));

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient cu = Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd");
Map<String, Object> params = new HashMap<String, Object>();
params.put("card", "tok_15cOky2eZvKYlo2CJpXkqmIV");
cu.createCard(params)

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.createCard(
  "rp_15cKMe2eZvKYlo2COsPyhwbd",
  {card: "tok_15cOky2eZvKYlo2CJpXkqmIV"},
  function(err, card) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.New(&stripe.CardParams{
  Recipient: "rp_15cKMe2eZvKYlo2COsPyhwbd",
  Token: "tok_15cOky2eZvKYlo2CJpXkqmIV",
}

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

#<Stripe::Card id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

<Card card  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

Stripe\Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

com.stripe.model.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

&stripe.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

Retrieve a card

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

Arguments

id required

The ID of the card to be retrieved.

Returns

Returns the card object.

Customer Recipient

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources/{CARD_ID}

customer = Stripe::Customer.retrieve({CUSTOMER_ID})
card = customer.sources.retrieve({CARD_ID})

customer = stripe.Customer.retrieve({CUSTOMER_ID})
card = customer.sources.retrieve({CARD_ID})

$customer = \Stripe\Customer::retrieve({CUSTOMER_ID});
$card = $customer->sources->retrieve({CARD_ID}));

Customer cu = Customer.retrieve({CUSTOMER_ID});
PaymentSource source = cu.getSources().retrieve({CARD_ID});
if (source.getObject().equals("card")) {
  Card card = (Card) source;
  // use the card!
}

stripe.customers.retrieveCard(
  {CUSTOMER_ID},
  {CARD_ID},
  function(card) {...}
);

c, err := card.Get({CARD_ID}, &stripe.CardParams{Customer: {CUSTOMER_ID}})

curl https://api.stripe.com/v1/customers/cus_5oWwNidx34nxOf/sources/card_15ctsW2eZvKYlo2CJXiRtE4j \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
card = customer.sources.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
card = customer.sources.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$card = $cu->sources->retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j");

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
PaymentSource source = cu.getSources().retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j");
if (source.getObject().equals("card")) {
  Card card = (Card) source;
  // use the card!
}

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.retrieveCard(
  "cus_5oWwNidx34nxOf",
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  function(err, card) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Get(
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  &stripe.CardParams{Customer: "cus_5oWwNidx34nxOf"}
)

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

#<Stripe::Card id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

<Card card  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

Stripe\Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

com.stripe.model.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

&stripe.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

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 rp = Recipient.retrieve({RECIPIENT_ID});
Card card = rp.cards->retrieve({CARD_ID});

stripe.recipients.retrieveCard(
  {RECIPIENT_ID},
  {CARD_ID},
  function(card) {...}
);

card.Get({CARD_ID}, &stripe.CardParams{Recipient: {RECIPIENT_ID}})

curl https://api.stripe.com/v1/recipients/rp_15cKMe2eZvKYlo2COsPyhwbd/cards/card_15ctsW2eZvKYlo2CJXiRtE4j \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd")
card = recipient.cards.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd")
card = recipient.cards.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$rp = \Stripe\Recipient::retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd");
$card = $rp->cards->retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j");

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd");
Card card = rp.getCards().retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j");

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.retrieveCard(
  "rp_15cKMe2eZvKYlo2COsPyhwbd",
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  function(err, card) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Get(
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  &stripe.CardParams{Recipient: "rp_15cKMe2eZvKYlo2COsPyhwbd"}
)

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

#<Stripe::Card id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

<Card card  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

Stripe\Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

com.stripe.model.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

&stripe.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

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
exp_month optional
exp_year optional
metadata optional
name optional

Returns

Returns the card object.

Customer Recipient

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources/{CARD_ID}

customer = Stripe::Customer.retrieve({CUSTOMER_ID})
card = customer.sources.retrieve({CARD_ID})
card.name = {NEW_NAME}
card.save

customer = stripe.Customer.retrieve({CUSTOMER_ID})
card = customer.sources.retrieve({CARD_ID})
card.name = {NEW_NAME}
card.save()

$customer = \Stripe\Customer::retrieve({CUSTOMER_ID});
$card = $customer->sources->retrieve({CARD_ID});
$card->name = {NEW_NAME};
$card->save();

Customer cu = Customer.retrieve({CUSTOMER_ID});
PaymentSource source = cu.getSources().retrieve({CARD_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("name", {NEW_NAME});
source.update(updateParams);

stripe.customers.updateCard({CUSTOMER_ID}, {CARD_ID}, {
  name: {NEW_NAME}
})

card.Update({CARD_ID},
  &stripe.CardParams{Customer: {CUSTOMER_ID}, Name: {NEW_NAME}}
)

curl https://api.stripe.com/v1/customers/cus_5oWwNidx34nxOf/sources/card_15ctsW2eZvKYlo2CJXiRtE4j \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="Jane Austen"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
card = customer.sources.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j")
card.name = "Jane Austen"
card.save

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
card = customer.sources.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j")
card.name = "Jane Austen"
card.save()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$card = $cu->sources->retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j");
$card->name = "Jane Austen";
$card->save();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
PaymentSource source = cu.getSources().retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j");
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_5oWwNidx34nxOf",
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  { name: "Jane Austen" },
  function(err, card) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Update(
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  &stripe.CardParams{
    Customer: "cus_5oWwNidx34nxOf",
    Name: "Jane Austen"
  }
)

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

#<Stripe::Card id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

<Card card  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

Stripe\Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

com.stripe.model.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

&stripe.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

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_15cKMe2eZvKYlo2COsPyhwbd/cards/card_15ctsW2eZvKYlo2CJXiRtE4j \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="Jane Austen"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd")
card = recipient.cards.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j")
card.name = "Jane Austen"
card.save

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd")
card = recipient.cards.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j")
card.name = "Jane Austen"
card.save()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$rp = \Stripe\Recipient::retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd");
$card = $rp->cards->retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j");
$card->name = "Jane Austen";
$card->save();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd");
Card card = rp.getCards().retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j");
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_15cKMe2eZvKYlo2COsPyhwbd",
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  { name: "Jane Austen" },
  function(err, card) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := card.Update(
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  &stripe.CardParams{
    Recipient: "rp_15cKMe2eZvKYlo2COsPyhwbd",
    Name: "Jane Austen"
  }
)

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

#<Stripe::Card id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

<Card card  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

Stripe\Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

com.stripe.model.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

{
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

&stripe.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

Delete a card

You can delete cards from a customer or recipient. If you delete a card that is currently the default source on a customer, 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. Similarly, if you delete the default card on a recipient, 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.

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 card to be deleted.

Returns

Returns the deleted card object.

Customer Recipient

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources/{CARD_ID}

customer = Stripe::Customer.retrieve({CUSTOMER_ID})
customer.sources.retrieve({CARD_ID}).delete()

customer = stripe.Customer.retrieve({CUSTOMER_ID})
customer.sources.retrieve({CARD_ID}).delete()

$customer = \Stripe\Customer::retrieve({CUSTOMER_ID});
$customer->sources->retrieve({CARD_ID})->delete();

Customer cu = Customer.retrieve({CUSTOMER_ID});
for(PaymentSource source : cu.getSources().getData()){
  if(source.getId().equals({CARD_ID})){
    source.delete();
    break;
  }
}

stripe.customers.deleteCard({CUSTOMER_ID}, {CARD_ID})

card.Del({CARD_ID}, &stripe.CardParams{Customer: {CUSTOMER_ID}})

curl https://api.stripe.com/v1/customers/cus_5oWwNidx34nxOf/sources/card_15ctsW2eZvKYlo2CJXiRtE4j \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
customer.sources.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j").delete

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
customer.sources.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j").delete()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$cu->sources->retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j")->delete();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
for(PaymentSource source : cu.getSources().getData()){
  if(source.getId().equals("card_15ctsW2eZvKYlo2CJXiRtE4j")){
    source.delete();
    break;
  }
}

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.deleteCard(
  "cus_5oWwNidx34nxOf",
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  function(err, confirmation) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := card.Del(
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  &stripe.CardParams{Customer: "cus_5oWwNidx34nxOf"}
)

{
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

#<Stripe::Object id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

<Object object  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

Stripe\Object JSON: {
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

com.stripe.model.Deletedcard JSON: {
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "deletedcard"
}

{
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

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_15cKMe2eZvKYlo2COsPyhwbd/cards/card_15ctsW2eZvKYlo2CJXiRtE4j \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = Stripe::Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd")
recipient.cards.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j").delete()

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

recipient = stripe.Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd")
recipient.cards.retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j").delete()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$rp = \Stripe\Recipient::retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd");
$rp->cards->retrieve("card_15ctsW2eZvKYlo2CJXiRtE4j")->delete();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Recipient rp = Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd");
for(Card card : rp.getCards().getData()){
  if(card.getId().equals("card_15ctsW2eZvKYlo2CJXiRtE4j")){
    card.delete();
    break;
  }
}

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.deleteCard(
  "rp_15cKMe2eZvKYlo2COsPyhwbd",
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  function(err, confirmation) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := card.Del(
  "card_15ctsW2eZvKYlo2CJXiRtE4j",
  &stripe.CardParams{Recipient: "rp_15cKMe2eZvKYlo2COsPyhwbd"}
)

{
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

#<Stripe::Object id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

<Object object  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

Stripe\Object JSON: {
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

com.stripe.model.Deletedcard JSON: {
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "deletedcard"
}

{
  "deleted": true,
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j"
}

nil

List all cards

You can see a list of the cards belonging to a customer or recipient. Note that the 10 most recent cards are always available by default on the customer or recipient 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 or recipient.

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

Customer Recipient

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/sources

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_15ctsW2eZvKYlo2Cl3IzoyWs/sources?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.retrieve("cu_15ctsW2eZvKYlo2Cl3IzoyWs").sources.all(:limit => 3, :object => "card")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.retrieve("cu_15ctsW2eZvKYlo2Cl3IzoyWs").sources.all(
  limit=3, object='card')

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

Customer cu = Customer.retrieve("cu_15ctsW2eZvKYlo2Cl3IzoyWs"); Map cardParams = new HashMap(); cardParams.put("limit", 3); cardParams.put("object", "card"); cu.getSources().all(cardParams);

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.listCards('cu_15ctsW2eZvKYlo2Cl3IzoyWs', function(err, cards) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CardListParams{Customer: "cu_15ctsW2eZvKYlo2Cl3IzoyWs"}
params.Filters.AddFilter("limit", "", "3")
i := card.List(params)
for i.Next() {
  c := i.Card()
}

{
  "object": "list",
  "url": "/v1/customers/cu_15ctsW2eZvKYlo2Cl3IzoyWs/sources",
  "has_more": false,
  "data": [
    {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_5oWwNidx34nxOf"
    },
    {...},
    {...}
  ]
}

#<Stripe::ListObject:0x3fe634d74498&gt JSON: {
  "object": "list",
  "url": "/v1/customers/cu_15ctsW2eZvKYlo2Cl3IzoyWs/sources",
  "has_more": false,
  "data": [
    #<Stripe::Card id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_5oWwNidx34nxOf"
    },
    #<Stripe::Card[...] ...>,
    #<Stripe::Card[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/customers/cu_15ctsW2eZvKYlo2Cl3IzoyWs/sources",
  has_more: false,
  data: [
    <Card card  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_5oWwNidx34nxOf"
    },
    <stripe.Card[...] ...>,
    <stripe.Card[...] ...>
  ]
}

Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/customers/cu_15ctsW2eZvKYlo2Cl3IzoyWs/sources",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Card JSON: {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_5oWwNidx34nxOf"
    }
    [1] => <Stripe\Card[...] ...>
    [2] => <Stripe\Card[...] ...>
  ]
}

#<com.stripe.model.CardCollection id=#> JSON: {
  "data": [
    com.stripe.model.Card JSON: {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_5oWwNidx34nxOf"
    },
    #<com.stripe.model.Card[...] ...>,
    #<com.stripe.model.Card[...] ...>
  ],
  "has_more": false
}

{
  "object": "list",
  "url": "/v1/customers/cu_15ctsW2eZvKYlo2Cl3IzoyWs/sources",
  "has_more": false,
  "data": [
    {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "customer": "cus_5oWwNidx34nxOf"
    },
    {...},
    {...}
  ]
}

&stripe.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "customer": "cus_5oWwNidx34nxOf"
}

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_15cKMe2eZvKYlo2COsPyhwbd/cards?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd").cards.all(:limit => 3)

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd").cards.all(
  limit=3)

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Recipient::retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd")->cards->all(array(
  'limit'=>3));

Recipient rp = Recipient.retrieve("rp_15cKMe2eZvKYlo2COsPyhwbd"); Map cardParams = new HashMap(); cardParams.put("limit", 3); RecipientCardCollection cards = rp.getCards().all(cardParams);

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.recipients.listCards('rp_15cKMe2eZvKYlo2COsPyhwbd', function(err, cards) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CardListParams{Recipient: "rp_15cKMe2eZvKYlo2COsPyhwbd"}
params.Filters.AddFilter("limit", "", "3")
i := card.List(params)
for i.Next() {
  c := i.Card()
}

{
  "object": "list",
  "url": "/v1/recipients/rp_15cKMe2eZvKYlo2COsPyhwbd/cards",
  "has_more": false,
  "data": [
    {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
    },
    {...},
    {...}
  ]
}

#<Stripe::ListObject:0x3fe634d74498&gt JSON: {
  "object": "list",
  "url": "/v1/recipients/rp_15cKMe2eZvKYlo2COsPyhwbd/cards",
  "has_more": false,
  "data": [
    #<Stripe::Card id=card_15ctsW2eZvKYlo2CJXiRtE4j 0x00000a> JSON: {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
    },
    #<Stripe::Card[...] ...>,
    #<Stripe::Card[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/recipients/rp_15cKMe2eZvKYlo2COsPyhwbd/cards",
  has_more: false,
  data: [
    <Card card  id=card_15ctsW2eZvKYlo2CJXiRtE4j at 0x00000a> JSON: {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
    },
    <stripe.Card[...] ...>,
    <stripe.Card[...] ...>
  ]
}

Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/recipients/rp_15cKMe2eZvKYlo2COsPyhwbd/cards",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Card JSON: {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
    }
    [1] => <Stripe\Card[...] ...>
    [2] => <Stripe\Card[...] ...>
  ]
}

#<com.stripe.model.CardCollection id=#> JSON: {
  "data": [
    com.stripe.model.Card JSON: {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
    },
    #<com.stripe.model.Card[...] ...>,
    #<com.stripe.model.Card[...] ...>
  ],
  "has_more": false
}

{
  "object": "list",
  "url": "/v1/recipients/rp_15cKMe2eZvKYlo2COsPyhwbd/cards",
  "has_more": false,
  "data": [
    {
      "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
      "object": "card",
      "last4": "4242",
      "brand": "Visa",
      "funding": "credit",
      "exp_month": 10,
      "exp_year": 2016,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "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,
      "dynamic_last4": null,
      "metadata": {
      },
      "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
    },
    {...},
    {...}
  ]
}

&stripe.Card JSON: {
  "id": "card_15ctsW2eZvKYlo2CJXiRtE4j",
  "object": "card",
  "last4": "4242",
  "brand": "Visa",
  "funding": "credit",
  "exp_month": 10,
  "exp_year": 2016,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "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,
  "dynamic_last4": null,
  "metadata": {
  },
  "recipient": "rp_15cKMe2eZvKYlo2COsPyhwbd"
}

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
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
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.
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.
tax_percent decimal

If provided, each invoice created by this subscription will apply the tax rate, increasing the amount billed to the customer.

{
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O 0x00000a> JSON: {
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O at 0x00000a> JSON: {
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWwNidx34nxOf/subscriptions \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d plan=-JYI_nRwd_ltcGRLnVys

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
customer.subscriptions.create(:plan => "-JYI_nRwd_ltcGRLnVys")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
customer.subscriptions.create(plan="-JYI_nRwd_ltcGRLnVys")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$cu->subscriptions->create(array("plan" => "-JYI_nRwd_ltcGRLnVys"));

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
Map<String, Object> params = new HashMap<String, Object>();
params.put("plan", "-JYI_nRwd_ltcGRLnVys");
cu.createSubscription(params)

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.createSubscription(
  "cus_5oWwNidx34nxOf",
  {plan: "-JYI_nRwd_ltcGRLnVys"},
  function(err, subscription) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

s, err := sub.New(&stripe.SubParams{
  Customer: "cus_5oWwNidx34nxOf",
  Plan: "-JYI_nRwd_ltcGRLnVys",
})

{
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O 0x00000a> JSON: {
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O at 0x00000a> JSON: {
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}

customer = Stripe::Customer.retrieve({CUSTOMER_ID})
subscription = customer.subscriptions.retrieve({SUBSCRIPTION_ID})

customer = stripe.Customer.retrieve({CUSTOMER_ID})
subscription = customer.subscriptions.retrieve({SUBSCRIPTION_ID})

$customer = \Stripe\Customer::retrieve({CUSTOMER_ID});
$subscription = $customer->subscriptions->retrieve({SUBSCRIPTION_ID}));

Customer cu = Customer.retrieve({CUSTOMER_ID});
Subscription subscription = cu.getSubscriptions().retrieve({SUBSCRIPTION_ID});

stripe.customers.retrieveSubscription(
  {CUSTOMER_ID},
  {SUBSCRIPTION_ID},
  function(subscription) {...}
);

s, err := sub.Get({SUBSCRIPTION_ID}, &stripe.SubParams{Customer: {CUSTOMER_ID}})

curl https://api.stripe.com/v1/customers/cus_5oWwNidx34nxOf/subscriptions/sub_5oWy917I8Re04O \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
subscription = customer.subscriptions.retrieve("sub_5oWy917I8Re04O")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
subscription = customer.subscriptions.retrieve("sub_5oWy917I8Re04O")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$subscription = $cu->subscriptions->retrieve("sub_5oWy917I8Re04O");

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
Subscription subscription = cu.getSubscriptions().retrieve("sub_5oWy917I8Re04O");

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.retrieveSubscription(
  "cus_5oWwNidx34nxOf",
  "sub_5oWy917I8Re04O",
  function(err, subscription) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

s, err := sub.Get(
      "sub_5oWy917I8Re04O",
      &stripe.SubParams{Customer: "cus_5oWwNidx34nxOf"}
    )

{
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O 0x00000a> JSON: {
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O at 0x00000a> JSON: {
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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.

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.
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_5oWwNidx34nxOf/subscriptions/sub_5oWy917I8Re04O \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d plan=-JYI_nRwd_ltcGRLnVys

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
subscription = customer.subscriptions.retrieve("sub_5oWy917I8Re04O")
subscription.plan = "-JYI_nRwd_ltcGRLnVys"
subscription.save

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
subscription = customer.subscriptions.retrieve("sub_5oWy917I8Re04O")
subscription.plan = "-JYI_nRwd_ltcGRLnVys"
subscription.save()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$subscription = $cu->subscriptions->retrieve("sub_5oWy917I8Re04O");
$subscription->plan = "-JYI_nRwd_ltcGRLnVys";
$subscription->save();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
Subscription subscription = cu.getSubscriptions().retrieve("sub_5oWy917I8Re04O");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("plan", "-JYI_nRwd_ltcGRLnVys");
subscription.update(updateParams);

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.updateSubscription(
  "cus_5oWwNidx34nxOf",
  "sub_5oWy917I8Re04O",
  { plan: "-JYI_nRwd_ltcGRLnVys" },
  function(err, subscription) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

s, err := sub.Update(
      "sub_5oWy917I8Re04O",
      &stripe.SubParams{
        Customer: "cus_5oWwNidx34nxOf",
        Plan: "-JYI_nRwd_ltcGRLnVys",
      }
    )

{
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O 0x00000a> JSON: {
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O at 0x00000a> JSON: {
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWwNidx34nxOf/subscriptions/sub_5oWy917I8Re04O \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
customer.subscriptions.retrieve("sub_5oWy917I8Re04O").delete

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
customer.subscriptions.retrieve("sub_5oWy917I8Re04O").delete()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$cu->subscriptions->retrieve("sub_5oWy917I8Re04O")->cancel();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
for(Subscription subscription : cu.getSubscriptions().getData()){
  if(subscription.getId().equals("sub_5oWy917I8Re04O")){
    subscription.cancel(null);
    break;
  }
}

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.cancelSubscription(
  "cus_5oWwNidx34nxOf",
  "sub_5oWy917I8Re04O",
  function(err, confirmation) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := sub.Cancel(
  "sub_5oWy917I8Re04O",
  &stripe.SubParams{Customer: "cus_5oWwNidx34nxOf"}
)

{
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "canceled",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O 0x00000a> JSON: {
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "canceled",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O at 0x00000a> JSON: {
  "id": "sub_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "canceled",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "canceled",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "deletedsubscription",
  "start": 1425542441,
  "status": "canceled",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "canceled",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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_15ctsW2eZvKYlo2Cl3IzoyWs/subscriptions?limit=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.retrieve("cu_15ctsW2eZvKYlo2Cl3IzoyWs").subscriptions.all(:limit => 3)

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.retrieve("cu_15ctsW2eZvKYlo2Cl3IzoyWs").subscriptions.all(
  limit=3)

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Customer::retrieve("cu_15ctsW2eZvKYlo2Cl3IzoyWs")->subscriptions->all(array(
  'limit'=>3));

Customer cu = Customer.retrieve("cu_15ctsW2eZvKYlo2Cl3IzoyWs"); Map subscriptionParams = new HashMap(); subscriptionParams.put("limit", 3); CustomerSubscriptionCollection subscriptions = cu.getSubscriptions().all(subscriptionParams);

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.listSubscriptions('cu_15ctsW2eZvKYlo2Cl3IzoyWs', function(err, subscriptions) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.SubListParams{Customer: "cu_15ctsW2eZvKYlo2Cl3IzoyWs"}
params.Filters.AddFilter("limit", "", "3")
i := sub.List(params)
for i.Next() {
  s := i.Sub()
}

{
  "object": "list",
  "url": "/v1/customers/cu_15ctsW2eZvKYlo2Cl3IzoyWs/subscriptions",
  "has_more": false,
  "data": [
    {
      "id": "sub_5oWy917I8Re04O",
      "plan": {
        "interval": "month",
        "name": "AAAAplanname",
        "created": 1412299176,
        "amount": 2000,
        "currency": "usd",
        "id": "-JYI_nRwd_ltcGRLnVys",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1425542441,
      "status": "active",
      "customer": "cus_5oWwNidx34nxOf",
      "cancel_at_period_end": false,
      "current_period_start": 1425542441,
      "current_period_end": 1428220841,
      "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&gt JSON: {
  "object": "list",
  "url": "/v1/customers/cu_15ctsW2eZvKYlo2Cl3IzoyWs/subscriptions",
  "has_more": false,
  "data": [
    #<Stripe::StripeObject id=sub_5oWy917I8Re04O 0x00000a> JSON: {
      "id": "sub_5oWy917I8Re04O",
      "plan": {
        "interval": "month",
        "name": "AAAAplanname",
        "created": 1412299176,
        "amount": 2000,
        "currency": "usd",
        "id": "-JYI_nRwd_ltcGRLnVys",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1425542441,
      "status": "active",
      "customer": "cus_5oWwNidx34nxOf",
      "cancel_at_period_end": false,
      "current_period_start": 1425542441,
      "current_period_end": 1428220841,
      "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_15ctsW2eZvKYlo2Cl3IzoyWs/subscriptions",
  has_more: false,
  data: [
    <StripeObject subscription  id=sub_5oWy917I8Re04O at 0x00000a> JSON: {
      "id": "sub_5oWy917I8Re04O",
      "plan": {
        "interval": "month",
        "name": "AAAAplanname",
        "created": 1412299176,
        "amount": 2000,
        "currency": "usd",
        "id": "-JYI_nRwd_ltcGRLnVys",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1425542441,
      "status": "active",
      "customer": "cus_5oWwNidx34nxOf",
      "cancel_at_period_end": false,
      "current_period_start": 1425542441,
      "current_period_end": 1428220841,
      "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_15ctsW2eZvKYlo2Cl3IzoyWs/subscriptions",
  "has_more" => false,
  "data" => [
    [0] => Stripe\StripeObject JSON: {
      "id": "sub_5oWy917I8Re04O",
      "plan": {
        "interval": "month",
        "name": "AAAAplanname",
        "created": 1412299176,
        "amount": 2000,
        "currency": "usd",
        "id": "-JYI_nRwd_ltcGRLnVys",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1425542441,
      "status": "active",
      "customer": "cus_5oWwNidx34nxOf",
      "cancel_at_period_end": false,
      "current_period_start": 1425542441,
      "current_period_end": 1428220841,
      "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_5oWy917I8Re04O",
      "plan": {
        "interval": "month",
        "name": "AAAAplanname",
        "created": 1412299176,
        "amount": 2000,
        "currency": "usd",
        "id": "-JYI_nRwd_ltcGRLnVys",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1425542441,
      "status": "active",
      "customer": "cus_5oWwNidx34nxOf",
      "cancel_at_period_end": false,
      "current_period_start": 1425542441,
      "current_period_end": 1428220841,
      "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_15ctsW2eZvKYlo2Cl3IzoyWs/subscriptions",
  "has_more": false,
  "data": [
    {
      "id": "sub_5oWy917I8Re04O",
      "plan": {
        "interval": "month",
        "name": "AAAAplanname",
        "created": 1412299176,
        "amount": 2000,
        "currency": "usd",
        "id": "-JYI_nRwd_ltcGRLnVys",
        "object": "plan",
        "livemode": false,
        "interval_count": 1,
        "trial_period_days": null,
        "metadata": {
        },
        "statement_descriptor": null
      },
      "object": "subscription",
      "start": 1425542441,
      "status": "active",
      "customer": "cus_5oWwNidx34nxOf",
      "cancel_at_period_end": false,
      "current_period_start": 1425542441,
      "current_period_end": 1428220841,
      "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_5oWy917I8Re04O",
  "plan": {
    "interval": "month",
    "name": "AAAAplanname",
    "created": 1412299176,
    "amount": 2000,
    "currency": "usd",
    "id": "-JYI_nRwd_ltcGRLnVys",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_descriptor": null
  },
  "object": "subscription",
  "start": 1425542441,
  "status": "active",
  "customer": "cus_5oWwNidx34nxOf",
  "cancel_at_period_end": false,
  "current_period_start": 1425542441,
  "current_period_end": 1428220841,
  "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.
name string

Display name of the plan
metadata metadata hash

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

Number of trial period days granted when subscribing a customer to this plan. Null if the plan has no trial period.
statement_descriptor string

Extra information about a charge for the customer’s credit card statement.

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

Specifies a trial period in (an integer number of) days. If you include a trial period, the customer won't be billed for the first time until the trial period ends. If the customer cancels before the trial period is over, she'll never be billed at all.
metadata optional, default is { }{ }{ }{ }{ }{ }{ }

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

An arbitrary string to be displayed on your customer's credit card statement. This may be up to22 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.

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": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

#<Stripe::Plan id=-JYI_nRwd_ltcGRLnVys 0x00000a> JSON: {
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

<Plan plan  id=-JYI_nRwd_ltcGRLnVys at 0x00000a> JSON: {
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

Stripe\Plan JSON: {
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

com.stripe.model.Plan JSON: {
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

{
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

&stripe.Plan JSON: {
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "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.

GET https://api.stripe.com/v1/plans/{PLAN_ID}

Stripe::Plan.retrieve({PLAN_ID})

stripe.Plan.retrieve({PLAN_ID})

\Stripe\Plan::retrieve({PLAN_ID});

Plan.retrieve({PLAN_ID});

stripe.plans.retrieve({PLAN_ID});

plan.Get({PLAN_ID})

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

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Plan.retrieve("-JYI_nRwd_ltcGRLnVys")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Plan.retrieve("-JYI_nRwd_ltcGRLnVys")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Plan::retrieve("-JYI_nRwd_ltcGRLnVys");

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Plan.retrieve("-JYI_nRwd_ltcGRLnVys");

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.plans.retrieve("-JYI_nRwd_ltcGRLnVys", function(err, plan) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p, err := plan.Get("-JYI_nRwd_ltcGRLnVys", nil)

{
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

#<Stripe::Plan id=-JYI_nRwd_ltcGRLnVys 0x00000a> JSON: {
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

<Plan plan  id=-JYI_nRwd_ltcGRLnVys at 0x00000a> JSON: {
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

Stripe\Plan JSON: {
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

com.stripe.model.Plan JSON: {
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

{
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

&stripe.Plan JSON: {
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "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

name optional

Name of the plan, to be displayed on invoices and in the web interface.
metadata optional, default is { }{ }{ }{ }{ }{ }{ }

A set of key/value pairs that you can attach to a plan object. It can be useful for storing additional information about the plan in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to nullnilNonenullnullnullnull and then saving. To clear all keys, set metadata to nullnilNonenullnullnullnull, then save.
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 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/-JYI_nRwd_ltcGRLnVys \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="New plan name"

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p = Stripe::Plan.retrieve("-JYI_nRwd_ltcGRLnVys")
p.name = "New plan name"
p.save

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p = stripe.Plan.retrieve("-JYI_nRwd_ltcGRLnVys")
p.name = "New plan name"
p.save()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$p = \Stripe\Plan::retrieve("-JYI_nRwd_ltcGRLnVys");
$p->name = "New plan name";
$p->save();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Plan p = Plan.retrieve("-JYI_nRwd_ltcGRLnVys");
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("-JYI_nRwd_ltcGRLnVys", {
  name: "New plan name"
}, function(err, plan) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

p, err := plan.Update(
      "-JYI_nRwd_ltcGRLnVys",
      &stripe.PlanParams{Name: "New plan name"}
    )

{
  "interval": "month",
  "name": "New plan name",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

#<Stripe::Plan id=-JYI_nRwd_ltcGRLnVys 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

<Plan plan  id=-JYI_nRwd_ltcGRLnVys at 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "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": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "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": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_descriptor": null
}

{
  "interval": "month",
  "name": "New plan name",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "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": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "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/-JYI_nRwd_ltcGRLnVys \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

plan = Stripe::Plan.retrieve("-JYI_nRwd_ltcGRLnVys")
plan.delete

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

plan = stripe.Plan.retrieve("-JYI_nRwd_ltcGRLnVys")
plan.delete()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$plan = \Stripe\Plan::retrieve("-JYI_nRwd_ltcGRLnVys");
$plan->delete();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Plan plan = Plan.retrieve("-JYI_nRwd_ltcGRLnVys");
plan.delete();

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.plans.del(
  "-JYI_nRwd_ltcGRLnVys",
  function(err, confirmation) {
    // asynchronously called
  }
);

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := plan.Del("-JYI_nRwd_ltcGRLnVys")

{
  "deleted": true,
  "id": "-JYI_nRwd_ltcGRLnVys"
}

#<Stripe::Object id=-JYI_nRwd_ltcGRLnVys 0x00000a> JSON: {
  "deleted": true,
  "id": "-JYI_nRwd_ltcGRLnVys"
}

<Object object  id=-JYI_nRwd_ltcGRLnVys at 0x00000a> JSON: {
  "deleted": true,
  "id": "-JYI_nRwd_ltcGRLnVys"
}

Stripe\Object JSON: {
  "deleted": true,
  "id": "-JYI_nRwd_ltcGRLnVys"
}

com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "-JYI_nRwd_ltcGRLnVys"
}

{
  "deleted": true,
  "id": "-JYI_nRwd_ltcGRLnVys"
}

nil

List all plans

Returns a list of your plans.

Arguments

created optional

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 dictionaryhashdictionaryassociative arrayMapobjectmap with the following options:
child arguments
- gtgtgtgtgtgtgt optional
  
  Return values where the created field is after this timestamp.
- gtegtegtegtegtegtegte optional
  
  Return values where the created field is after or equal to this timestamp.
- ltltltltltltlt optional
  
  Return values where the created field is before this timestamp.
- lteltelteltelteltelte 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 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Plan.all

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Plan.all()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Plan::all();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Plan.all(new HashMap<String, Object>());

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.plans.list(function(err, plans) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

i := plan.List(nil)
for i.Next() {
  p := i.Plan()
}

{
  "object": "list",
  "url": "/v1/plans",
  "has_more": false,
  "data": [
    {
      "interval": "month",
      "name": "AAAAplanname",
      "created": 1412299176,
      "amount": 2000,
      "currency": "usd",
      "id": "-JYI_nRwd_ltcGRLnVys",
      "object": "plan",
      "livemode": false,
      "interval_count": 1,
      "trial_period_days": null,
      "metadata": {
      },
      "statement_descriptor": null
    },
    {...},
    {...}
  ]
}

#<Stripe::ListObject:0x3fe634d74498&gt JSON: {
  "object": "list",
  "url": "/v1/plans",
  "has_more": false,
  "data": [
    #<Stripe::Plan id=-JYI_nRwd_ltcGRLnVys 0x00000a> JSON: {
      "interval": "month",
      "name": "AAAAplanname",
      "created": 1412299176,
      "amount": 2000,
      "currency": "usd",
      "id": "-JYI_nRwd_ltcGRLnVys",
      "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=-JYI_nRwd_ltcGRLnVys at 0x00000a> JSON: {
      "interval": "month",
      "name": "AAAAplanname",
      "created": 1412299176,
      "amount": 2000,
      "currency": "usd",
      "id": "-JYI_nRwd_ltcGRLnVys",
      "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": "AAAAplanname",
      "created": 1412299176,
      "amount": 2000,
      "currency": "usd",
      "id": "-JYI_nRwd_ltcGRLnVys",
      "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": "AAAAplanname",
      "created": 1412299176,
      "amount": 2000,
      "currency": "usd",
      "id": "-JYI_nRwd_ltcGRLnVys",
      "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": "AAAAplanname",
      "created": 1412299176,
      "amount": 2000,
      "currency": "usd",
      "id": "-JYI_nRwd_ltcGRLnVys",
      "object": "plan",
      "livemode": false,
      "interval_count": 1,
      "trial_period_days": null,
      "metadata": {
      },
      "statement_descriptor": null
    },
    {...},
    {...}
  ]
}

{
  "interval": "month",
  "name": "AAAAplanname",
  "created": 1412299176,
  "amount": 2000,
  "currency": "usd",
  "id": "-JYI_nRwd_ltcGRLnVys",
  "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.
amount_off positive integer

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

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

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

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

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

Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. For example, a coupon with percent_off of 50 will make a $100 invoice $50 instead.
redeem_by timestamp

Date after which the coupon can no longer be redeemed
times_redeemed positive integer or zero

Number of times this coupon has been applied to a customer.
valid boolean

Taking account of the above properties, whether this coupon can still be applied to a customer

{
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}#<Stripe::Coupon id=20152CLOUD35 0x00000a> JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}<Coupon coupon  id=20152CLOUD35 at 0x00000a> JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}Stripe\Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}com.stripe.model.Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}{
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}&stripe.Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

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"

coupon.New(&stripe.CouponParams{
  Percent: 25,
  Duration: "repeating",
  DurationPeriod: 3,
  Id: "250FF",
})

{
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

#<Stripe::Coupon id=20152CLOUD35 0x00000a> JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

<Coupon coupon  id=20152CLOUD35 at 0x00000a> JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

Stripe\Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

com.stripe.model.Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

{
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

&stripe.Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

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.

GET https://api.stripe.com/v1/coupons/{COUPON_ID}

Stripe::Coupon.retrieve({COUPON_ID})

stripe.Coupon.retrieve({COUPON_ID})

\Stripe\Coupon::retrieve({COUPON_ID});

Coupon.retrieve({COUPON_ID});

stripe.coupons.retrieve({COUPON_ID});

coupon.Get({COUPON_ID})

curl https://api.stripe.com/v1/coupons/20152CLOUD35 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Coupon.retrieve("20152CLOUD35")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Coupon.retrieve("20152CLOUD35")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Coupon::retrieve("20152CLOUD35");

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon.retrieve("20152CLOUD35");

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.retrieve("20152CLOUD35", function(err, coupon) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := coupon.Get("20152CLOUD35", nil)

{
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

#<Stripe::Coupon id=20152CLOUD35 0x00000a> JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

<Coupon coupon  id=20152CLOUD35 at 0x00000a> JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

Stripe\Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

com.stripe.model.Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

{
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

&stripe.Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

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/20152CLOUD35 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d metadata[key]=value

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

coupon = Stripe::Coupon.retrieve("20152CLOUD35")
coupon.metadata["key"] = "value"
coupon.save

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

coupon = stripe.Coupon.retrieve("20152CLOUD35")
coupon.metadata["key"] = "value"
coupon.save()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$coupon = $cu->coupons->retrieve("20152CLOUD35");
$coupon->metadata["key"] = "value";
$coupon->save();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon coupon = Coupon.retrieve("20152CLOUD35");
Map metadata = new HashMap();
metdata.put("key", "value");
Map params = new HashMap();
params.put("metadata", metadata);
refund.update(params);

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.update("20152CLOUD35", {
  metadata: {key: "value"}
)

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

c, err := coupon.Update(
      "20152CLOUD35",
      &stripe.CouponParams{Meta: map[string]string{"key": "value"}}
)

{
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "key": "value"
  }
}

#<Stripe::Coupon id=20152CLOUD35 0x00000a> JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "key": "value"
  }
}

<Coupon coupon  id=20152CLOUD35 at 0x00000a> JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "key": "value"
  }
}

Stripe\Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "key": "value"
  }
}

com.stripe.model.Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "key": "value"
  }
}

{
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "key": "value"
  }
}

&stripe.Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "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/20152CLOUD35 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cpn = Stripe::Coupon.retrieve("20152CLOUD35")
cpn.delete

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cpn = stripe.Coupon.retrieve("20152CLOUD35")
cpn.delete()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cpn = \Stripe\Coupon::retrieve("20152CLOUD35");
$cpn->delete();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon cpn = Coupon.retrieve("20152CLOUD35");
cpn.delete();

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.del("20152CLOUD35")

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := coupon.Del("20152CLOUD35")

{
  "deleted": true,
  "id": "20152CLOUD35"
}

#<Stripe::Object id=20152CLOUD35 0x00000a> JSON: {
  "deleted": true,
  "id": "20152CLOUD35"
}

<Object object  id=20152CLOUD35 at 0x00000a> JSON: {
  "deleted": true,
  "id": "20152CLOUD35"
}

Stripe\Object JSON: {
  "deleted": true,
  "id": "20152CLOUD35"
}

com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "20152CLOUD35"
}

{
  "deleted": true,
  "id": "20152CLOUD35"
}

nil

List all coupons

Returns a list of your coupons.

Arguments

created optional

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 dictionaryhashdictionaryassociative arrayMapobjectmap with the following options:
child arguments
- gtgtgtgtgtgtgt optional
  
  Return values where the created field is after this timestamp.
- gtegtegtegtegtegtegte optional
  
  Return values where the created field is after or equal to this timestamp.
- ltltltltltltlt optional
  
  Return values where the created field is before this timestamp.
- lteltelteltelteltelte 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 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Coupon.all

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Coupon.all()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Coupon::all();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon.all(new HashMap<String, Object>());

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.list({ 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": "20152CLOUD35",
      "created": 1424904798,
      "percent_off": 35,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "once",
      "redeem_by": 1424991198,
      "max_redemptions": null,
      "times_redeemed": 0,
      "duration_in_months": null,
      "valid": false,
      "metadata": {
        "coupon-type": "subscription-yearly",
        "promotion": "mktg_winback35_20150225"
      }
    },
    {...},
    {...}
  ]
}

#<Stripe::ListObject:0x3fe634d74498&gt JSON: {
  "object": "list",
  "url": "/v1/coupons",
  "has_more": false,
  "data": [
    #<Stripe::Coupon id=20152CLOUD35 0x00000a> JSON: {
      "id": "20152CLOUD35",
      "created": 1424904798,
      "percent_off": 35,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "once",
      "redeem_by": 1424991198,
      "max_redemptions": null,
      "times_redeemed": 0,
      "duration_in_months": null,
      "valid": false,
      "metadata": {
        "coupon-type": "subscription-yearly",
        "promotion": "mktg_winback35_20150225"
      }
    },
    #<Stripe::Coupon[...] ...>,
    #<Stripe::Coupon[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/coupons",
  has_more: false,
  data: [
    <Coupon coupon  id=20152CLOUD35 at 0x00000a> JSON: {
      "id": "20152CLOUD35",
      "created": 1424904798,
      "percent_off": 35,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "once",
      "redeem_by": 1424991198,
      "max_redemptions": null,
      "times_redeemed": 0,
      "duration_in_months": null,
      "valid": false,
      "metadata": {
        "coupon-type": "subscription-yearly",
        "promotion": "mktg_winback35_20150225"
      }
    },
    <stripe.Coupon[...] ...>,
    <stripe.Coupon[...] ...>
  ]
}

Stripe\Collection JSON: {
  "object" => "list",
  "url" => "/v1/coupons",
  "has_more" => false,
  "data" => [
    [0] => Stripe\Coupon JSON: {
      "id": "20152CLOUD35",
      "created": 1424904798,
      "percent_off": 35,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "once",
      "redeem_by": 1424991198,
      "max_redemptions": null,
      "times_redeemed": 0,
      "duration_in_months": null,
      "valid": false,
      "metadata": {
        "coupon-type": "subscription-yearly",
        "promotion": "mktg_winback35_20150225"
      }
    }
    [1] => <Stripe\Coupon[...] ...>
    [2] => <Stripe\Coupon[...] ...>
  ]
}

#<com.stripe.model.CouponCollection id=#> JSON: {
  "data": [
    com.stripe.model.Coupon JSON: {
      "id": "20152CLOUD35",
      "created": 1424904798,
      "percent_off": 35,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "once",
      "redeem_by": 1424991198,
      "max_redemptions": null,
      "times_redeemed": 0,
      "duration_in_months": null,
      "valid": false,
      "metadata": {
        "coupon-type": "subscription-yearly",
        "promotion": "mktg_winback35_20150225"
      }
    },
    #<com.stripe.model.Coupon[...] ...>,
    #<com.stripe.model.Coupon[...] ...>
  ],
  "has_more": false
}

{
  "object": "list",
  "url": "/v1/coupons",
  "has_more": false,
  "data": [
    {
      "id": "20152CLOUD35",
      "created": 1424904798,
      "percent_off": 35,
      "amount_off": null,
      "currency": "usd",
      "object": "coupon",
      "livemode": false,
      "duration": "once",
      "redeem_by": 1424991198,
      "max_redemptions": null,
      "times_redeemed": 0,
      "duration_in_months": null,
      "valid": false,
      "metadata": {
        "coupon-type": "subscription-yearly",
        "promotion": "mktg_winback35_20150225"
      }
    },
    {...},
    {...}
  ]
}

&stripe.Coupon JSON: {
  "id": "20152CLOUD35",
  "created": 1424904798,
  "percent_off": 35,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "once",
  "redeem_by": 1424991198,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
    "coupon-type": "subscription-yearly",
    "promotion": "mktg_winback35_20150225"
  }
}

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": "20152CLOUD35",
    "created": 1424904798,
    "percent_off": 35,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "once",
    "redeem_by": 1424991198,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
      "coupon-type": "subscription-yearly",
      "promotion": "mktg_winback35_20150225"
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_5oWwNidx34nxOf",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}#<Stripe::Discount 0x00000a> JSON: {
  "coupon": {
    "id": "20152CLOUD35",
    "created": 1424904798,
    "percent_off": 35,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "once",
    "redeem_by": 1424991198,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
      "coupon-type": "subscription-yearly",
      "promotion": "mktg_winback35_20150225"
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_5oWwNidx34nxOf",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}<Discount discount  at 0x00000a> JSON: {
  "coupon": {
    "id": "20152CLOUD35",
    "created": 1424904798,
    "percent_off": 35,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "once",
    "redeem_by": 1424991198,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
      "coupon-type": "subscription-yearly",
      "promotion": "mktg_winback35_20150225"
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_5oWwNidx34nxOf",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}Stripe\Discount JSON: {
  "coupon": {
    "id": "20152CLOUD35",
    "created": 1424904798,
    "percent_off": 35,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "once",
    "redeem_by": 1424991198,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
      "coupon-type": "subscription-yearly",
      "promotion": "mktg_winback35_20150225"
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_5oWwNidx34nxOf",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}com.stripe.model.Discount JSON: {
  "coupon": {
    "id": "20152CLOUD35",
    "created": 1424904798,
    "percent_off": 35,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "once",
    "redeem_by": 1424991198,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
      "coupon-type": "subscription-yearly",
      "promotion": "mktg_winback35_20150225"
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_5oWwNidx34nxOf",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}{
  "coupon": {
    "id": "20152CLOUD35",
    "created": 1424904798,
    "percent_off": 35,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "once",
    "redeem_by": 1424991198,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
      "coupon-type": "subscription-yearly",
      "promotion": "mktg_winback35_20150225"
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_5oWwNidx34nxOf",
  "subscription": "sub_4avT2dbwKJA3EL",
  "end": null
}&stripe.Discount JSON: {
  "coupon": {
    "id": "20152CLOUD35",
    "created": 1424904798,
    "percent_off": 35,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "once",
    "redeem_by": 1424991198,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
      "coupon-type": "subscription-yearly",
      "promotion": "mktg_winback35_20150225"
    }
  },
  "start": 1408104978,
  "object": "discount",
  "customer": "cus_5oWwNidx34nxOf",
  "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_5oWwNidx34nxOf/discount \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
cu.delete_discount

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
cu.delete_discount()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$cu->deleteDiscount();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
cu.deleteDiscount();

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.deleteDiscount("cus_5oWwNidx34nxOf", function(err, confirmation) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := discount.Del("cus_5oWwNidx34nxOf")

{
  "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_5oWwNidx34nxOf/subscriptions/sub_5oWy917I8Re04O/discount \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETE

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_5oWwNidx34nxOf")
cu.subscriptions.retrieve("sub_5oWy917I8Re04O").delete_discount()

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_5oWwNidx34nxOf")
cu.subscriptions.retrieve("sub_5oWy917I8Re04O").delete_discount()

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = \Stripe\Customer::retrieve("cus_5oWwNidx34nxOf");
$cu->subscriptions->retrieve("sub_5oWy917I8Re04O")->deleteDiscount();

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_5oWwNidx34nxOf");
cu.subscriptions.retrieve("sub_5oWy917I8Re04O").deleteDiscount();

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.deleteSubscriptionDiscount("cus_5oWwNidx34nxOf", "sub_5oWy917I8Re04O", function(err, confirmation) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

err := discount.DelSub(
      "cus_5oWwNidx34nxOf",
      "sub_5oWy917I8Re04O"
)

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

{
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "sub_5oWy917I8Re04O",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1428220841,
          "end": 1430812841
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "AAAAplanname",
          "created": 1412299176,
          "amount": 2000,
          "currency": "usd",
          "id": "-JYI_nRwd_ltcGRLnVys",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}#<Stripe::Invoice id=in_15ctsW2eZvKYlo2C7tYfubmp 0x00000a> JSON: {
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "sub_5oWy917I8Re04O",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1428220841,
          "end": 1430812841
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "AAAAplanname",
          "created": 1412299176,
          "amount": 2000,
          "currency": "usd",
          "id": "-JYI_nRwd_ltcGRLnVys",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}<Invoice invoice  id=in_15ctsW2eZvKYlo2C7tYfubmp at 0x00000a> JSON: {
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "sub_5oWy917I8Re04O",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1428220841,
          "end": 1430812841
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "AAAAplanname",
          "created": 1412299176,
          "amount": 2000,
          "currency": "usd",
          "id": "-JYI_nRwd_ltcGRLnVys",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}Stripe\Invoice JSON: {
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "sub_5oWy917I8Re04O",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1428220841,
          "end": 1430812841
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "AAAAplanname",
          "created": 1412299176,
          "amount": 2000,
          "currency": "usd",
          "id": "-JYI_nRwd_ltcGRLnVys",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}com.stripe.model.Invoice JSON: {
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "sub_5oWy917I8Re04O",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1428220841,
          "end": 1430812841
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "AAAAplanname",
          "created": 1412299176,
          "amount": 2000,
          "currency": "usd",
          "id": "-JYI_nRwd_ltcGRLnVys",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}{
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "sub_5oWy917I8Re04O",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1428220841,
          "end": 1430812841
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "AAAAplanname",
          "created": 1412299176,
          "amount": 2000,
          "currency": "usd",
          "id": "-JYI_nRwd_ltcGRLnVys",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}&stripe.Invoice JSON: {
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "sub_5oWy917I8Re04O",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1428220841,
          "end": 1430812841
        },
        "subscription": null,
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "AAAAplanname",
          "created": 1412299176,
          "amount": 2000,
          "currency": "usd",
          "id": "-JYI_nRwd_ltcGRLnVys",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_descriptor": null
        },
        "description": null,
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "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
period hash

The period this line_item covers
proration boolean

Whether or not this is a proration
type string

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

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

Key-value pairs attached to the line item, if the line item is an invoice item
plan hash, plan object

The plan of the subscription, if the line item is a subscription 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_15cKMf2eZvKYlo2CJVQZgmly",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 12345,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1425405809,
    "end": 1425405809
  },
  "subscription": null,
  "quantity": null,
  "plan": null,
  "description": "INVOICE ALL THE THINGS",
  "metadata": {
  }
}#<Stripe::LineItem id=ii_15cKMf2eZvKYlo2CJVQZgmly 0x00000a> JSON: {
  "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 12345,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1425405809,
    "end": 1425405809
  },
  "subscription": null,
  "quantity": null,
  "plan": null,
  "description": "INVOICE ALL THE THINGS",
  "metadata": {
  }
}<LineItem line_item  id=ii_15cKMf2eZvKYlo2CJVQZgmly at 0x00000a> JSON: {
  "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 12345,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1425405809,
    "end": 1425405809
  },
  "subscription": null,
  "quantity": null,
  "plan": null,
  "description": "INVOICE ALL THE THINGS",
  "metadata": {
  }
}Stripe\LineItem JSON: {
  "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 12345,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1425405809,
    "end": 1425405809
  },
  "subscription": null,
  "quantity": null,
  "plan": null,
  "description": "INVOICE ALL THE THINGS",
  "metadata": {
  }
}com.stripe.model.LineItem JSON: {
  "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 12345,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1425405809,
    "end": 1425405809
  },
  "subscription": null,
  "quantity": null,
  "plan": null,
  "description": "INVOICE ALL THE THINGS",
  "metadata": {
  }
}{
  "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 12345,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1425405809,
    "end": 1425405809
  },
  "subscription": null,
  "quantity": null,
  "plan": null,
  "description": "INVOICE ALL THE THINGS",
  "metadata": {
  }
}&stripe.LineItem JSON: {
  "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 12345,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1425405809,
    "end": 1425405809
  },
  "subscription": null,
  "quantity": null,
  "plan": null,
  "description": "INVOICE ALL THE THINGS",
  "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_5oWwNidx34nxOf

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Invoice.create(
    :customer => "cus_5oWwNidx34nxOf"
)

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.create(
    customer="cus_5oWwNidx34nxOf"
)

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Invoice::create(array(
    "customer" => "cus_5oWwNidx34nxOf"
));

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

Invoice.create(invoiceParams);

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoices.create({
  customer: "cus_5oWwNidx34nxOf"
}, function(err, invoice) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

i, err := invoice.New(&stripe.InvoiceParams{Customer: "cus_5oWwNidx34nxOf"})

{
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 25000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1425405809,
          "end": 1425405809
        },
        "subscription": null,
        "quantity": null,
        "plan": null,
        "description": "INVOICE ALL THE THINGS",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}

#<Stripe::Invoice id=in_15ctsW2eZvKYlo2C7tYfubmp 0x00000a> JSON: {
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 25000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1425405809,
          "end": 1425405809
        },
        "subscription": null,
        "quantity": null,
        "plan": null,
        "description": "INVOICE ALL THE THINGS",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}

<Invoice invoice  id=in_15ctsW2eZvKYlo2C7tYfubmp at 0x00000a> JSON: {
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 25000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1425405809,
          "end": 1425405809
        },
        "subscription": null,
        "quantity": null,
        "plan": null,
        "description": "INVOICE ALL THE THINGS",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}

Stripe\Invoice JSON: {
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 25000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1425405809,
          "end": 1425405809
        },
        "subscription": null,
        "quantity": null,
        "plan": null,
        "description": "INVOICE ALL THE THINGS",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}

com.stripe.model.Invoice JSON: {
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 25000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1425405809,
          "end": 1425405809
        },
        "subscription": null,
        "quantity": null,
        "plan": null,
        "description": "INVOICE ALL THE THINGS",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}

{
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 25000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1425405809,
          "end": 1425405809
        },
        "subscription": null,
        "quantity": null,
        "plan": null,
        "description": "INVOICE ALL THE THINGS",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "tax_percent": null,
  "tax": null,
  "metadata": {
  },
  "statement_descriptor": null,
  "description": null,
  "receipt_number": null
}

&stripe.Invoice JSON: {
  "date": 1425542324,
  "id": "in_15ctsW2eZvKYlo2C7tYfubmp",
  "period_start": 1425542324,
  "period_end": 1425542324,
  "lines": {
    "data": [
      {
        "id": "ii_15cKMf2eZvKYlo2CJVQZgmly",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 25000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1425405809,
          "end": 1425405809
        },
        "subscription": null,
        "quantity": null,
        "plan": null,
        "description": "INVOICE ALL THE THINGS",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_15ctsW2eZvKYlo2C7tYfubmp/lines"
  },
  "subtotal": 25000,
  "total": 25000,
  "customer": "cus_5oWwNidx34nxOf",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "forgiven": false,
  "paid": true,
  "livemode": false,
  "attempt_count": 1,
  "amount_due": 25000,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": 0,
  "next_payment_attempt": null,
  "webhooks_delivered_at": 1425542335,
  "charge": "ch_15ctsW2eZvKYlo2CAb7RTMhn",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_5oWwPSOxF6rEpI",
  "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.

GET https://api.stripe.com/v1/invoices/{INVOICE_ID}

Stripe::Invoice.retrieve({INVOICE_ID})

stripe.Invoice.retrieve({INVOICE_ID})

\Stripe\Invoice::retrieve({INVOICE_ID});

Invoice.retrieve({INVOICE_ID});

stripe.invoices.retrieve({INVOICE_ID});

invoice.Get({INVOICE_ID})

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

require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Invoice.retrieve("in_15ctsW2eZvKYlo2C7tYfubmp")

import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.retrieve("in_15ctsW2eZvKYlo2C7tYfubmp")

\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Invoice::retrieve("in_15ctsW2eZvKYlo2C7tYfubmp");

Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Invoice.retrieve("in_15ctsW2eZvKYlo2C7tYfubmp");

var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoices.retrieve("in_15ctsW2eZvKYlo2C7tYfubmp", function(err, invoice) {
  // asynchronously called
});

stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

i, err := invo

API Reference

Libraries

Authentication

Errors

Attributes

type

message optional

code optional

param optional

HTTP Status Code Summary

Errors

Handling errors

Pagination

Arguments

limit optional

starting_after optional

ending_before optional

List Response Format

object string, value is "list"

data array

has_more boolean

url string

Versioning

Expanding objects

Metadata

Sample metadata use cases

Link IDs

Shipping information

Product plan

Idempotent requests

Charges

The charge object

Attributes

id string

object string , value is "charge"

livemode boolean

amount positive integer or zero

captured boolean

created timestamp

currency currency

paid boolean

refunded boolean

refunds list

child attributes

object string , value is "list"

data list

child attributes

id string

object string , value is "list"

amount integer

created timestamp

currency currency

balance_transaction string

charge string

metadata metadata hash

reason string

receipt_number string

description string

has_more boolean

url string

total_count positive integer or zero

source hash

status string

amount_refunded positive integer or zero

balance_transaction string

customer string

description string

dispute hash, dispute object

failure_code string

failure_message string

invoice string

metadata metadata hash

receipt_email string

receipt_number string

fraud_details hash

shipping hash or null

child attributes

address hash

child attributes

line1 string