API Reference

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

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

Libraries

Libraries are available in several languages.

API Endpoint

https://api.stripe.com/

Summary of Resource URL Patterns

/v1/charges
/v1/charges/{CHARGE_ID}
/v1/coupons
/v1/coupons/{COUPON_ID}
/v1/customers
/v1/customers/{CUSTOMER_ID}
/v1/customers/{CUSTOMER_ID}/subscription
/v1/invoices
/v1/invoices/{INVOICE_ID}
/v1/invoices/{INVOICE_ID}/lines
/v1/invoiceitems
/v1/invoiceitems/{INVOICEITEM_ID}
/v1/plans
/v1/plans/{PLAN_ID}
/v1/tokens
/v1/tokens/{TOKEN_ID}
/v1/events
/v1/events/{EVENT_ID}

Authentication

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

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

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

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

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

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

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

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

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

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

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

Errors

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

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

Attributes

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

HTTP Status Code Summary

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

Errors

Types

invalid_request_error	Invalid request errors arise when your request has invalid parameters.
api_error	API errors cover any other type of problem (e.g. a temporary problem with Stripe's servers) and should turn up only very infrequently.
card_error	Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason.

Codes

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

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

Handling errors

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

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

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

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

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

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

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

Pagination

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

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

Pagination Arguments

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

List Response Format

object: string, value is "list"
data: array An array containing the actual response elements, paginated by any request parameters.
has_more: boolean Whether or not there are more elements available after this page. If false, this page is the end of the list.
url: string The URL where this list can be accessed.

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

Stripe::Customer.allimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.all()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Customer::all();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer.all(new HashMap<String, Object>());var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

{
  "object": "list",
  "url": "v1/customers",
  "has_more": false,
  "data": [
    {
    "object": "customer",
    "created": 1398323226,
    "id": "cus_3uVyE6e5atTTQE",
    "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_3uVyE6e5atTTQE/subscriptions",
      "data": [
        {
          "id": "sub_3uVyZtqbGP43Gy",
          "plan": {
            "interval": "month",
            "name": "PricingPlan 69",
            "created": 1398323226,
            "amount": 69,
            "currency": "usd",
            "id": "TestMode4",
            "object": "plan",
            "livemode": false,
            "interval_count": 1,
            "trial_period_days": 5,
            "metadata": {
            },
            "statement_description": null
          },
          "object": "subscription",
          "start": 1398323228,
          "status": "trialing",
          "customer": "cus_3uVyE6e5atTTQE",
          "cancel_at_period_end": true,
          "current_period_start": 1398323228,
          "current_period_end": 1398755228,
          "ended_at": null,
          "trial_start": 1398323228,
          "trial_end": 1398755228,
          "canceled_at": 1398323229,
          "quantity": 1,
          "application_fee_percent": null,
          "discount": null
        }
      ]
    },
    "discount": null,
    "account_balance": 0,
    "currency": "usd",
    "cards": {
      "object": "list",
      "total_count": 0,
      "has_more": false,
      "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
      "data": [
  
      ]
    },
    "default_card": null
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "v1/customers",
  "data": [
    #<Stripe::Customer id=cus_3uVyE6e5atTTQE 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
},
    #<Stripe::Customer[...] ...>,
    #<Stripe::Customer[...] ...>
  ]
}

{
  object: "list",
  url: "v1/customers",
  has_more: false,
  data: [
    <Customer customer  id=cus_3uVyE6e5atTTQE at 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
},
    <stripe.Customer[...] ...>,
    <stripe.Customer[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "v1/customers",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}
    [1] => <Stripe_Customer[...] ...>
    [2] => <Stripe_Customer[...] ...>
  )
)
#<com.stripe.model.CustomerCollection id=#> JSON: {
  "data": [
    com.stripe.model.Customer JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
},
    #<com.stripe.model.Customer[...] ...>,
    #<com.stripe.model.Customer[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "v1/customers",
  "has_more": false,
  "data": [
    {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
},
    {...},
    {...}
  ]
}

Versioning

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

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

Expanding Objects

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

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

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

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

stripe.Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg", expand=['customer'])require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

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

Metadata

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

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

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

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

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

Sample metadata use cases

Link IDs: Attach your system's unique IDs to a Stripe object for easy lookups. Add an order number to a charge, your user ID to a customer or recipient, or a unique receipt number to a transfer, for example.
Shipping information: Store shipping status and tracking numbers on a charge to easily track the status of an order.
Product plan: Annotate a customer, charge, recipient, or transfer with the product in use. For example, a charge may have been made under an 'enterprise' or 'personal' product.

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

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

stripe.Charge.create(
  amount=400,
  currency="usd",
  card="tok_103uT82eZvKYlo2CZCUY8fPs", # obtained with Stripe.js
  metadata={'order_id': '6735'}
)require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Charge::create(array(
  "amount" => 400,
  "currency" => "usd",
  "card" => "tok_103uT82eZvKYlo2CZCUY8fPs", // obtained with Stripe.js,
  "metadata" => array("order_id" => "6735")
));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

stripe.charges.create({
  amount: 400,
  currency: "usd",
  card: "tok_103uT82eZvKYlo2CZCUY8fPs", // obtained with Stripe.js
  metadata: {'order_id': '6735'}
});

{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_description": null
}#<Stripe::Charge id=ch_103uVx2eZvKYlo2CO1scPlyg 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_description": null
}<Charge charge  id=ch_103uVx2eZvKYlo2CO1scPlyg at 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_description": null
}com.stripe.model.Charge JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
    "order_id": "6735"
  },
  "statement_description": null
}

Charges

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

The charge object

Attributes

id

string

object

string, value is "charge"

livemode

boolean

amount

positive integer or zero Amount charged in cents

captured

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

card

hash, card object Hash describing the card used to make the charge

created

timestamp

currency

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

paid

boolean

refunded

boolean Whether or not the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.

refunds

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

object: string
amount: integer Amount refunded, in cents.
created: timestamp
currency: currency Three-letter ISO code representing the currency of the refund.
balance_transaction: string or null Balance transaction that describes the impact of this refund on your account balance.

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 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 https://stripe.com/docs/api#errors for a list of codes)

failure_message

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

invoice

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.

statement_description

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

{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}#<Stripe::Charge id=ch_103uVx2eZvKYlo2CO1scPlyg 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}<Charge charge  id=ch_103uVx2eZvKYlo2CO1scPlyg at 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}com.stripe.model.Charge JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}

Creating a new charge (charging a credit card)

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

Arguments

amount

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

currency

required 3-letter ISO code for currency.

customer

optional, either customer or card is required The ID of an existing customer that will be charged in this request.

card

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

numbernumbernumbernumbernumbernumber: required The card number, as a string without any separators.
exp_monthexp_monthexp_monthexp_monthexp_monthexp_month: required Two digit number representing the card's expiration month.
exp_yearexp_yearexp_yearexp_yearexp_yearexp_year: required Two or four digit number representing the card's expiration year.
cvccvccvccvccvccvc: optional, highly recommended Card security code.
namenamenamenamenamename: optional Cardholder's full name.
address_line1address_line1address_line1address_line1address_line1address_line1: optional
address_line2address_line2address_line2address_line2address_line2address_line2: optional
address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city: optional
address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip: optional
address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state: optional
address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country: optional

description

optional, default is nullnilNonenullnullnull An arbitrary string which you can attach to a charge object. It is displayed when in the web interface alongside the charge. Note that if you use Stripe to send automatic email receipts to your customers, your receipt emails will include the description of the charge(s) that they are describing.

metadata

optional, default is { } A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format. It's often a good idea to store an email address in metadata for tracking later.

capture

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

statement_description

optional, default is nullnilNonenullnullnull An arbitrary string to be displayed alongside your company name on your customer's credit card statement. This may be up to 15 characters. As an example, if your website is RunClub and you specify 5K Race Ticket, the user will see
RUNCLUB 5K RACE TICKET. The statement description may not include <>"' characters. While most banks display this information consistently, some may display it incorrectly or not at all.

application_fee

optional A fee in cents that will be applied to the charge and transferred to the application owner's Stripe account. The request must be made with an OAuth key in order to take an application fee. For more information, see the application fees documentation.

Returns

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

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

POST https://api.stripe.com/v1/chargesStripe::Charge.createstripe.Charge.create()Stripe_Charge::create();Charge.create();stripe.charges.create();

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=400 \
   -d currency=usd \
   -d card=tok_103uT82eZvKYlo2CZCUY8fPs \
   -d "description=Charge for test@example.com"require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Charge.create(
  :amount => 400,
  :currency => "usd",
  :card => "tok_103uT82eZvKYlo2CZCUY8fPs", # obtained with Stripe.js
  :description => "Charge for test@example.com"
)import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Charge.create(
  amount=400,
  currency="usd",
  card="tok_103uT82eZvKYlo2CZCUY8fPs", # obtained with Stripe.js
  description="Charge for test@example.com"
)require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Charge::create(array(
  "amount" => 400,
  "currency" => "usd",
  "card" => "tok_103uT82eZvKYlo2CZCUY8fPs", // obtained with Stripe.js
  "description" => "Charge for test@example.com"
));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

stripe.charges.create({
  amount: 400,
  currency: "usd",
  card: "tok_103uT82eZvKYlo2CZCUY8fPs", // obtained with Stripe.js
  description: "Charge for test@example.com"
});

{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}#<Stripe::Charge id=ch_103uVx2eZvKYlo2CO1scPlyg 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}<Charge charge  id=ch_103uVx2eZvKYlo2CO1scPlyg at 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}com.stripe.model.Charge JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}

Verification Reponses

CVC Verification - `card[cvc_check]`

Code	Details
pass	The CVC provided is correct
fail	The CVC provided is incorrect
unchecked	The customer's bank did not check the CVC

Address Line - `card[address_line1_check]`

Code	Details
pass	The first address line provided is correct
fail	The first address line provided is incorrect
unchecked	The customer's bank did not check the first address line

Address ZIP - `card[address_zip_check]`

Code	Details
pass	The ZIP code provided is correct
fail	The ZIP code provided is incorrect
unchecked	The customer's bank did not check the ZIP code

Retrieving a Charge

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

Arguments

id: required The identifier of the charge to be retrieved.

Returns

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

GET https://api.stripe.com/v1/charges/{CHARGE_ID}Stripe::Charge.retrieve({CHARGE_ID})stripe.Charge.retrieve({CHARGE_ID})Stripe_Charge::retrieve({CHARGE_ID});Charge.retrieve({CHARGE_ID});stripe.charges.retrieve({CHARGE_ID});

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

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

stripe.Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Charge::retrieve("ch_103uVx2eZvKYlo2CO1scPlyg");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}#<Stripe::Charge id=ch_103uVx2eZvKYlo2CO1scPlyg 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}<Charge charge  id=ch_103uVx2eZvKYlo2CO1scPlyg at 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}com.stripe.model.Charge JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}

Updating a Charge

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

This request accepts only the description and metadata as arguments.

Arguments

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

Returns

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

POST https://api.stripe.com/v1/charges/{CHARGE_ID}ch = Stripe::Charge.retrieve({CHARGE_ID})
ch.description = {NEW_DESCRIPTION}
...
cu.save
ch = stripe.Charge.retrieve({CHARGE_ID})
ch.description = {NEW_DESCRIPTION}
...
ch.save()
$ch = Stripe_Charge::retrieve({CHARGE_ID});
$ch->description = {NEW_DESCRIPTION};
...
$ch->save();
Charge ch = Charge.retrieve({CHARGE_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", {NEW_DESCRIPTION});
...
ch.update(updateParams);stripe.charges.update({CHARGE_ID}, {
  description: {NEW_DESCRIPTION}
});

curl https://api.stripe.com/v1/charges/ch_103uVx2eZvKYlo2CO1scPlyg \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d "description=Charge for test@example.com"require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")
ch.description = "Charge for test@example.com"
ch.saveimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")
ch.description = "Charge for test@example.com"
ch.save()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

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

{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}#<Stripe::Charge id=ch_103uVx2eZvKYlo2CO1scPlyg 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}<Charge charge  id=ch_103uVx2eZvKYlo2CO1scPlyg at 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}com.stripe.model.Charge JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [

  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 0,
  "customer": null,
  "invoice": null,
  "description": "Charge for test@example.com",
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}

Refunding a Charge

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

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

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

Arguments

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

Returns

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

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/refundch = Stripe::Charge.retrieve({CHARGE_ID})
ch.refund
ch = stripe.Charge.retrieve({CHARGE_ID})
ch.refund()
$ch = Stripe_Charge::retrieve({CHARGE_ID});
$ch->refund();
ch = Charge.retrieve({CHARGE_ID});
ch.refund();
stripe.charges.refund({CHARGE_ID});

curl https://api.stripe.com/v1/charges/ch_103uVx2eZvKYlo2CO1scPlyg/refund \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POSTrequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")
ch.refundimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")
ch.refund()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = Stripe_Charge::retrieve("ch_103uVx2eZvKYlo2CO1scPlyg");
$ch->refund();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

ch = Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg");
ch.refund();var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": true,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}#<Stripe::Charge id=ch_103uVx2eZvKYlo2CO1scPlyg 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": true,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}<Charge charge  id=ch_103uVx2eZvKYlo2CO1scPlyg at 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": true,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": true,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}com.stripe.model.Charge JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": true,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": true,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}

Capture a charge

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

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

Arguments

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

Returns

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

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/capturech = Stripe::Charge.retrieve({CHARGE_ID})
ch.capture
ch = stripe.Charge.retrieve({CHARGE_ID})
ch.capture()
$ch = Stripe_Charge::retrieve({CHARGE_ID});
$ch->capture();
ch = Charge.retrieve({CHARGE_ID});
ch.capture();
stripe.charges.capture({CHARGE_ID});

curl https://api.stripe.com/v1/charges/ch_103uVx2eZvKYlo2CO1scPlyg/capture \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POSTrequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = Stripe::Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")
ch.captureimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ch = stripe.Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")
ch.capture()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = Stripe_Charge::retrieve("ch_103uVx2eZvKYlo2CO1scPlyg");
$ch->capture();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}#<Stripe::Charge id=ch_103uVx2eZvKYlo2CO1scPlyg 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}<Charge charge  id=ch_103uVx2eZvKYlo2CO1scPlyg at 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": "True",
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}com.stripe.model.Charge JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": "true",
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": "true",
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}

List all Charges

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

Arguments

created

optional A filter on the list based on the object created field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:

gtgtgtgtgtgt: optional Return values where the created field is after this timestamp.
gtegtegtegtegtegte: optional Return values where the created field is after or equal to this timestamp.
ltltltltltlt: optional Return values where the created field is before this timestamp.
ltelteltelteltelte: 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 arrayMapobject with a data property that contains an array of up to limit charges, starting after charge starting_after. Each entry in the array is a separate charge object. If no more charges are available, the resulting array will be empty. If you provide a non-existent customer ID, this call returnsraisesraisesthrowsthrowsthrows an error.

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

GET https://api.stripe.com/v1/chargesStripe::Charge.allstripe.Charge.all()Stripe_Charge::all();Charge.all(Map options);stripe.charges.list();

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

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

stripe.Charge.all(count=3)require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Charge::all(array("count" => 3));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

stripe.charges.list({ count: 3 }, function(err, charges) {
  // asynchronously called
});

{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
    "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
    "object": "charge",
    "created": 1398323170,
    "livemode": false,
    "paid": true,
    "amount": 500,
    "currency": "usd",
    "refunded": false,
    "card": {
      "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
      "object": "card",
      "last4": "4242",
      "type": "Visa",
      "exp_month": 1,
      "exp_year": 2050,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "customer": null,
      "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
    },
    "captured": true,
    "refunds": [
      {
        "amount": 500,
        "currency": "usd",
        "created": 1398323301,
        "object": "refund",
        "balance_transaction": "txn_3uW03bX4vEgHqP"
      }
    ],
    "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
    "failure_message": null,
    "failure_code": null,
    "amount_refunded": 500,
    "customer": null,
    "invoice": null,
    "description": null,
    "dispute": null,
    "metadata": {
    },
    "statement_description": null
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "/v1/charges",
  "data": [
    #<Stripe::Charge id=ch_103uVx2eZvKYlo2CO1scPlyg 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
},
    #<Stripe::Charge[...] ...>,
    #<Stripe::Charge[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/charges",
  has_more: false,
  data: [
    <Charge charge  id=ch_103uVx2eZvKYlo2CO1scPlyg at 0x00000a> JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
},
    <stripe.Charge[...] ...>,
    <stripe.Charge[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "/v1/charges",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}
    [1] => <Stripe_Charge[...] ...>
    [2] => <Stripe_Charge[...] ...>
  )
)
#<com.stripe.model.ChargeCollection id=#> JSON: {
  "data": [
    com.stripe.model.Charge JSON: {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
},
    #<com.stripe.model.Charge[...] ...>,
    #<com.stripe.model.Charge[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/charges",
  "has_more": false,
  "data": [
    {
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": false,
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
},
    {...},
    {...}
  ]
}

Customers

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

The customer object

Attributes

id

string

object

string, value is "customer"

livemode

boolean

cards

list

object: string list
data: array, contains: card object
has_more: boolean
url: string The URL where this list can be accessed.
total_count: positive integer or zero or null The total number of items available. This value is not included by default, but you can request it by specifying ?include[]=total_count

created

timestamp

account_balance

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

currency

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

default_card

string ID of the default credit card attached to the 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.

subscriptions

list The customer’s current subscriptions, if any

object: string 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 or null 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": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}#<Stripe::Customer id=cus_3uVyE6e5atTTQE 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}<Customer customer  id=cus_3uVyE6e5atTTQE at 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}com.stripe.model.Customer JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}

Creating a New Customer

Creates a new customer object.

Arguments

account_balance

optional An integer amount in cents that is the starting account balance for your customer. A negative amount represents a credit that will be used before attempting any charges to the customer’s card; a positive amount will be added to the next invoice.

card

optional The card can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below). Passing card will create a new card, make it the new customer default card, and delete the old customer default if one exists. If you want to add additional cards instead of replacing the existing default, use the card creation API. Whenever you attach a card to a customer, Stripe will automatically validate the card.

numbernumbernumbernumbernumbernumber: required The card number, as a string without any separators.
exp_monthexp_monthexp_monthexp_monthexp_monthexp_month: required Two digit number representing the card's expiration month.
exp_yearexp_yearexp_yearexp_yearexp_yearexp_year: required Two or four digit number representing the card's expiration year.
cvccvccvccvccvccvc: optional, highly recommended Card security code.
namenamenamenamenamename: optional Cardholder's full name.
address_line1address_line1address_line1address_line1address_line1address_line1: optional
address_line2address_line2address_line2address_line2address_line2address_line2: optional
address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city: optional
address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip: optional
address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state: optional
address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country: optional

coupon

optional If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the API will not have the discount.

description

optional An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.

email

optional Customer’s email address. It’s displayed alongside the customer in your dashboard and can be useful for searching and tracking. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.

metadata

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

plan

optional The identifier of the plan to subscribe the customer to. If provided, the returned customer object has a ‘subscription’ attribute describing the state of the customer’s subscription

quantity

optional The quantity you’d like to apply to the subscription you’re creating. For example, if your plan is 10 cents/user/month, and your customer has 5 users, you could pass 5 as the quantity to have the customer charged 50 cents (5 x 10 cents) monthly. Defaults to 1 if not set. Only applies when the plan parameter is also provided.

trial_end

optional UTC integer timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer’s trial immediately. Only applies when the plan parameter is also provided.

Returns

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

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

POST https://api.stripe.com/v1/customersStripe::Customer.createstripe.Customer.create()Stripe_Customer::create();Customer.create();stripe.customers.create();

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

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

stripe.Customer.create(
  description="Customer for test@example.com",
  card="tok_103uT82eZvKYlo2CZCUY8fPs" # obtained with Stripe.js
)require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Customer::create(array(
  "description" => "Customer for test@example.com",
  "card" => "tok_103uT82eZvKYlo2CZCUY8fPs" // obtained with Stripe.js
));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("description", "Customer for test@example.com");
customerParams.put("card", "tok_103uT82eZvKYlo2CZCUY8fPs"); // obtained with Stripe.js

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

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

{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}#<Stripe::Customer id=cus_3uVyE6e5atTTQE 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}<Customer customer  id=cus_3uVyE6e5atTTQE at 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}com.stripe.model.Customer JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}

Retrieving a Customer

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

Arguments

id: required The identifier of the customer to be retrieved.

Returns

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

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}Stripe::Customer.retrieve({CUSTOMER_ID})stripe.Customer.retrieve({CUSTOMER_ID})Stripe_Customer::retrieve({CUSTOMER_ID});Customer.retrieve({CUSTOMER_ID});stripe.customers.retrieve({CUSTOMER_ID});

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

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

stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer.retrieve("cus_3uVyE6e5atTTQE");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}#<Stripe::Customer id=cus_3uVyE6e5atTTQE 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}<Customer customer  id=cus_3uVyE6e5atTTQE at 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}com.stripe.model.Customer JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}

Updating a Customer

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

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

Arguments

account_balance

optional An integer amount in cents that is the starting account balance for your customer. A negative amount represents a credit that will be used before attempting any charges to the customer’s card; a positive amount will be added to the next invoice.

card

optional The card can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below). Passing card will create a new card, make it the new customer default card, and delete the old customer default if one exists. If you want to add additional cards instead of replacing the existing default, use the card creation API. Whenever you attach a card to a customer, Stripe will automatically validate the card.

numbernumbernumbernumbernumbernumber: required The card number, as a string without any separators.
exp_monthexp_monthexp_monthexp_monthexp_monthexp_month: required Two digit number representing the card's expiration month.
exp_yearexp_yearexp_yearexp_yearexp_yearexp_year: required Two or four digit number representing the card's expiration year.
cvccvccvccvccvccvc: optional, highly recommended Card security code.
namenamenamenamenamename: optional Cardholder's full name.
address_line1address_line1address_line1address_line1address_line1address_line1: optional
address_line2address_line2address_line2address_line2address_line2address_line2: optional
address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city: optional
address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip: optional
address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state: optional
address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country: optional

coupon

optional If you provide a coupon code, the customer will have a discount applied on all recurring charges. Charges you create through the API will not have the discount.

default_card

optional ID of card to make the customer’s new default for invoice payments

description

optional An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.

email

optional Customer’s email address. It’s displayed alongside the customer in your dashboard and can be useful for searching and tracking. This will be unset if you POST an empty value.This can be unset by updating the value to nullnilNonenullnullnull and then saving.

metadata

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

Returns

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

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}cu = Stripe::Customer.retrieve({CUSTOMER_ID})
cu.description = {NEW_DESCRIPTION}
...
cu.save
cu = stripe.Customer.retrieve({CUSTOMER_ID})
cu.description = {NEW_DESCRIPTION}
...
cu.save()
$cu = Stripe_Customer::retrieve({CUSTOMER_ID});
$cu->description = {NEW_DESCRIPTION};
...
$cu->save();
Customer cu = Customer.retrieve({CUSTOMER_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", {NEW_DESCRIPTION});
...
cu.update(updateParams);stripe.customers.update({CUSTOMER_ID}, {
  description: {NEW_DESCRIPTION},
  ...
});

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

cu = Stripe::Customer.retrieve("cus_3uVyE6e5atTTQE")
cu.description = "Customer for test@example.com"
cu.card = "tok_103uT82eZvKYlo2CZCUY8fPs" # obtained with Stripe.js
cu.saveimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
cu.description = "Customer for test@example.com"
cu.save()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$cu->description = "Customer for test@example.com";
$cu->card = "tok_103uT82eZvKYlo2CZCUY8fPs"; // obtained with Stripe.js
$cu->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}#<Stripe::Customer id=cus_3uVyE6e5atTTQE 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}<Customer customer  id=cus_3uVyE6e5atTTQE at 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}com.stripe.model.Customer JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}{
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}

Deleting a Customer

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

Arguments

id: required The identifier of the customer to be deleted.

Returns

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

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

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}cu = Stripe::Customer.retrieve({CUSTOMER_ID})
cu.delete
cu = stripe.Customer.retrieve({CUSTOMER_ID})
cu.delete()
$cu = Stripe_Customer::retrieve({CUSTOMER_ID});
$cu->delete();
Customer cu = Customer.retrieve({CUSTOMER_ID});
cu.delete();
stripe.customers.del({CUSTOMER_ID});

curl https://api.stripe.com/v1/customers/cus_3uVyE6e5atTTQE \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETErequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_3uVyE6e5atTTQE")
cu.deleteimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
cu.delete()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$cu->delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

{
  "deleted": true,
  "id": "cus_3uVyE6e5atTTQE"
}#<Stripe::Object id=cus_3uVyE6e5atTTQE 0x00000a> JSON: {
  "deleted": true,
  "id": "cus_3uVyE6e5atTTQE"
}<Object object  id=cus_3uVyE6e5atTTQE at 0x00000a> JSON: {
  "deleted": true,
  "id": "cus_3uVyE6e5atTTQE"
}{
  "deleted": true,
  "id": "cus_3uVyE6e5atTTQE"
}com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "cus_3uVyE6e5atTTQE"
}{
  "deleted": true,
  "id": "cus_3uVyE6e5atTTQE"
}

List all Customers

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

Arguments

created

optional A filter on the list based on the object created field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:

gtgtgtgtgtgt: optional Return values where the created field is after this timestamp.
gtegtegtegtegtegte: optional Return values where the created field is after or equal to this timestamp.
ltltltltltlt: optional Return values where the created field is before this timestamp.
ltelteltelteltelte: 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 arrayMapobject with a data property that contains an array of up to limit customers, starting after customer starting_after. Each entry in the array is a separate customer object. If no more customers are available, the resulting array will be empty. This request should never returnraiseraisethrowthrowthrow an error.

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

GET https://api.stripe.com/v1/customersStripe::Customer.allstripe.Customer.all()Stripe_Customer::all();Customer.all(Map options);stripe.customers.list();

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

Stripe::Customer.allimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.all()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Customer::all();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer.all(new HashMap<String, Object>());var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

{
  "object": "list",
  "url": "v1/customers",
  "has_more": false,
  "data": [
    {
    "object": "customer",
    "created": 1398323226,
    "id": "cus_3uVyE6e5atTTQE",
    "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_3uVyE6e5atTTQE/subscriptions",
      "data": [
        {
          "id": "sub_3uVyZtqbGP43Gy",
          "plan": {
            "interval": "month",
            "name": "PricingPlan 69",
            "created": 1398323226,
            "amount": 69,
            "currency": "usd",
            "id": "TestMode4",
            "object": "plan",
            "livemode": false,
            "interval_count": 1,
            "trial_period_days": 5,
            "metadata": {
            },
            "statement_description": null
          },
          "object": "subscription",
          "start": 1398323228,
          "status": "trialing",
          "customer": "cus_3uVyE6e5atTTQE",
          "cancel_at_period_end": true,
          "current_period_start": 1398323228,
          "current_period_end": 1398755228,
          "ended_at": null,
          "trial_start": 1398323228,
          "trial_end": 1398755228,
          "canceled_at": 1398323229,
          "quantity": 1,
          "application_fee_percent": null,
          "discount": null
        }
      ]
    },
    "discount": null,
    "account_balance": 0,
    "currency": "usd",
    "cards": {
      "object": "list",
      "total_count": 0,
      "has_more": false,
      "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
      "data": [
  
      ]
    },
    "default_card": null
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "v1/customers",
  "data": [
    #<Stripe::Customer id=cus_3uVyE6e5atTTQE 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
},
    #<Stripe::Customer[...] ...>,
    #<Stripe::Customer[...] ...>
  ]
}

{
  object: "list",
  url: "v1/customers",
  has_more: false,
  data: [
    <Customer customer  id=cus_3uVyE6e5atTTQE at 0x00000a> JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
},
    <stripe.Customer[...] ...>,
    <stripe.Customer[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "v1/customers",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
}
    [1] => <Stripe_Customer[...] ...>
    [2] => <Stripe_Customer[...] ...>
  )
)
#<com.stripe.model.CustomerCollection id=#> JSON: {
  "data": [
    com.stripe.model.Customer JSON: {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
},
    #<com.stripe.model.Customer[...] ...>,
    #<com.stripe.model.Customer[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "v1/customers",
  "has_more": false,
  "data": [
    {
  "object": "customer",
  "created": 1398323226,
  "id": "cus_3uVyE6e5atTTQE",
  "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_3uVyE6e5atTTQE/subscriptions",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "object": "subscription",
        "start": 1398323228,
        "status": "trialing",
        "customer": "cus_3uVyE6e5atTTQE",
        "cancel_at_period_end": true,
        "current_period_start": 1398323228,
        "current_period_end": 1398755228,
        "ended_at": null,
        "trial_start": 1398323228,
        "trial_end": 1398755228,
        "canceled_at": 1398323229,
        "quantity": 1,
        "application_fee_percent": null,
        "discount": null
      }
    ]
  },
  "discount": null,
  "account_balance": 0,
  "currency": "usd",
  "cards": {
    "object": "list",
    "total_count": 0,
    "has_more": false,
    "url": "/v1/customers/cus_3uVyE6e5atTTQE/cards",
    "data": [

    ]
  },
  "default_card": null
},
    {...},
    {...}
  ]
}

Cards

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

The card object

Attributes

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

{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}#<Stripe::Card id=card_103uVy2eZvKYlo2CjKliwa3N 0x00000a> JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}<Card card  id=card_103uVy2eZvKYlo2CjKliwa3N at 0x00000a> JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}com.stripe.model.Card JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}

Creating a new card

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

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

Arguments

card

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

numbernumbernumbernumbernumbernumber: required The card number, as a string without any separators.
exp_monthexp_monthexp_monthexp_monthexp_monthexp_month: required Two digit number representing the card's expiration month.
exp_yearexp_yearexp_yearexp_yearexp_yearexp_year: required Two or four digit number representing the card's expiration year.
cvccvccvccvccvccvc: optional, highly recommended Card security code.
namenamenamenamenamename: optional Cardholder's full name.
address_line1address_line1address_line1address_line1address_line1address_line1: optional
address_line2address_line2address_line2address_line2address_line2address_line2: optional
address_cityaddress_cityaddress_cityaddress_cityaddress_cityaddress_city: optional
address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip: optional
address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state: optional
address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country: optional

Returns

Returns the card object.

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/cardscustomer = Stripe::Customer.retrieve({CUSTOMER_ID})
customer.cards.create({:card => TOKEN_ID})
customer = stripe.Customer.retrieve({CUSTOMER_ID})
customer.cards.create(card={TOKEN_ID})
$customer = Stripe_Customer::retrieve({CUSTOMER_ID});
$customer.cards->create(array("card" => {TOKEN_ID}));
Customer cu = Customer.retrieve({CUSTOMER_ID});
Map params = new HashMap();
params.put("card", {TOKEN_ID});
cu.cards->create(params);
stripe.customers.createCard({CUSTOMER_ID}, {
  card: {TOKEN_ID}
});

curl https://api.stripe.com/v1/customers/cus_3uVyE6e5atTTQE/cards \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d card=token_idrequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_3uVyE6e5atTTQE")
customer.cards.create(:card => "tok_103uT82eZvKYlo2CZCUY8fPs")import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
customer.cards.create(card="tok_103uT82eZvKYlo2CZCUY8fPs")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$cu->cards->create(array("card" => "tok_103uT82eZvKYlo2CZCUY8fPs"));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}#<Stripe::Card id=card_103uVy2eZvKYlo2CjKliwa3N 0x00000a> JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}<Card card  id=card_103uVy2eZvKYlo2CjKliwa3N at 0x00000a> JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}com.stripe.model.Card JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}

Retrieving a customer's card

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

Arguments

id: required ID of card to retrieve
customer: required

Returns

Returns the card object.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/cards/{CARD_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID})
card = customer.cards.retrieve({CARD_ID})
customer = stripe.Customer.retrieve({CUSTOMER_ID})
card = customer.cards.retrieve({CARD_ID})
$customer = Stripe_Customer::retrieve({CUSTOMER_ID});
$card = $customer->cards->retrieve({CARD_ID}));
Customer cu = Customer.retrieve({CUSTOMER_ID});
Card card = cu.cards->retrieve({CARD_ID});
stripe.customers.retrieveCard(
  {CUSTOMER_ID},
  {CARD_ID},
  function(card) {...}
);

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

customer = Stripe::Customer.retrieve("cus_3uVyE6e5atTTQE")
card = customer.cards.retrieve("card_103uVy2eZvKYlo2CjKliwa3N")import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
card = customer.cards.retrieve("card_103uVy2eZvKYlo2CjKliwa3N")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$card = $cu->cards->retrieve("card_103uVy2eZvKYlo2CjKliwa3N");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_3uVyE6e5atTTQE");
Card card = cu.getCards().retrieve("card_103uVy2eZvKYlo2CjKliwa3N");var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}#<Stripe::Card id=card_103uVy2eZvKYlo2CjKliwa3N 0x00000a> JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}<Card card  id=card_103uVy2eZvKYlo2CjKliwa3N at 0x00000a> JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}com.stripe.model.Card JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}

Updating a card

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

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

Arguments

address_city: optional
address_country: optional
address_line1: optional
address_line2: optional
address_state: optional
address_zip: optional
exp_month: optional
exp_year: optional
name: optional

Returns

Returns the card object.

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/cards/{CARD_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID})
card = customer.cards.retrieve({CARD_ID})
card.name = {NEW_NAME}
card.save
customer = stripe.Customer.retrieve({CUSTOMER_ID})
card = customer.cards.retrieve({CARD_ID})
card.name = {NEW_NAME}
card.save()
$customer = Stripe_Customer::retrieve({CUSTOMER_ID});
$card = $customer->cards->retrieve({CARD_ID}));
$card->name = {NEW_NAME};
$card->save();
Customer cu = Customer.retrieve({CUSTOMER_ID});
Card card = cu.cards->retrieve({CARD_ID});
Map updateParams = new HashMap();
updateParams.put("name", {NEW_NAME});
card.update(updateParams);
stripe.customers.updateCard({CUSTOMER_ID}, {CARD_ID}, {
  name: {NEW_NAME}
})

curl https://api.stripe.com/v1/customers/cus_3uVyE6e5atTTQE/cards/card_103uVy2eZvKYlo2CjKliwa3N \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d "name=Jane Austen"require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_3uVyE6e5atTTQE")
card = customer.cards.retrieve("card_103uVy2eZvKYlo2CjKliwa3N")
card.name = "Jane Austen"
card.saveimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
card = customer.cards.retrieve("card_103uVy2eZvKYlo2CjKliwa3N")
card.name = "Jane Austen"
card.save()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$card = $cu->cards->retrieve("card_103uVy2eZvKYlo2CjKliwa3N");
$card->name = "Jane Austen";
$card->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_3uVyE6e5atTTQE");
Card card = cu.getCards().retrieve("card_103uVy2eZvKYlo2CjKliwa3N");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("name", "Jane Austen");
card.update(updateParams);var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.customers.updateCard(
  "cus_3uVyE6e5atTTQE",
  "card_103uVy2eZvKYlo2CjKliwa3N",
  { name: "Jane Austen" },
  function(err, card) {
    // asynchronously called
  }
);

{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "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": null,
  "address_line1_check": null,
  "address_zip_check": null
}#<Stripe::Card id=card_103uVy2eZvKYlo2CjKliwa3N 0x00000a> JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "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": null,
  "address_line1_check": null,
  "address_zip_check": null
}<Card card  id=card_103uVy2eZvKYlo2CjKliwa3N at 0x00000a> JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "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": null,
  "address_line1_check": null,
  "address_zip_check": null
}{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "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": null,
  "address_line1_check": null,
  "address_zip_check": null
}com.stripe.model.Card JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "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": null,
  "address_line1_check": null,
  "address_zip_check": null
}{
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": "cus_3uVyE6e5atTTQE",
  "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": null,
  "address_line1_check": null,
  "address_zip_check": null
}

Deleting cards

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

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

Arguments

id: required
customer: required

Returns

Returns the deleted card object.

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/cards/{CARD_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID})
customer.cards.retrieve({CARD_ID}).delete()
customer = stripe.Customer.retrieve({CUSTOMER_ID})
customer.cards.retrieve({CARD_ID}).delete()
$customer = Stripe_Customer::retrieve({CUSTOMER_ID});
$customer->cards->retrieve({CARD_ID})->delete();
Customer cu = Customer.retrieve({CUSTOMER_ID});
for(Card card : cu.getCards().getData()){
  if(card.getId().equals({CARD_ID})){
    card.delete();
    break;
  }
}
stripe.customers.deleteCard({CUSTOMER_ID}, {CARD_ID})

curl https://api.stripe.com/v1/customers/cus_3uVyE6e5atTTQE/cards/card_103uVy2eZvKYlo2CjKliwa3N \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETErequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_3uVyE6e5atTTQE")
customer.cards.retrieve("card_103uVy2eZvKYlo2CjKliwa3N").delete()import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
customer.cards.retrieve("card_103uVy2eZvKYlo2CjKliwa3N").delete()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$cu->cards->retrieve("card_103uVy2eZvKYlo2CjKliwa3N")->delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_3uVyE6e5atTTQE");
for(Card card : cu.getCards().getData()){
  if(card.getId().equals("card_103uVy2eZvKYlo2CjKliwa3N")){
    card.delete();
    break;
  }
}var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

{
  "deleted": true,
  "id": "card_103uVy2eZvKYlo2CjKliwa3N"
}#<Stripe::Object id=card_103uVy2eZvKYlo2CjKliwa3N 0x00000a> JSON: {
  "deleted": true,
  "id": "card_103uVy2eZvKYlo2CjKliwa3N"
}<Object object  id=card_103uVy2eZvKYlo2CjKliwa3N at 0x00000a> JSON: {
  "deleted": true,
  "id": "card_103uVy2eZvKYlo2CjKliwa3N"
}{
  "deleted": true,
  "id": "card_103uVy2eZvKYlo2CjKliwa3N"
}com.stripe.model.Deletedcard JSON: {
  "deleted": true,
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "deletedcard"
}{
  "deleted": true,
  "id": "card_103uVy2eZvKYlo2CjKliwa3N"
}

Listing cards

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

Arguments

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

Returns

Returns a list of the customer's stored cards.

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

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/cardsStripe::Customer.retrieve({CUSTOMER_ID}).cards.all()stripe.Customer.retrieve({CUSTOMER_ID}).cards.all()Stripe_Customer::retrieve({CUSTOMER_ID})->cards->all();Customer.retrieve({CUSTOMER_ID}).getCards().all();stripe.customers.listCards({CUSTOMER_ID});

curl https://api.stripe.com/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/cards?count=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Customer.retrieve("cu_103uVy2eZvKYlo2CxtIYScP2").cards.all(:count => 3)import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Customer.retrieve("cu_103uVy2eZvKYlo2CxtIYScP2").cards.all(
  count=3)require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Customer::retrieve("cu_103uVy2eZvKYlo2CxtIYScP2")->cards->all(array(
  'count'=>3));Customer cu = Customer.retrieve("cu_103uVy2eZvKYlo2CxtIYScP2");
Map cardParams = new HashMap();
cardParams.put("count", 3);
CustomerCardCollection cards = cu.getCards().all(cardParams);
stripe.customers.listCards('cu_103uVy2eZvKYlo2CxtIYScP2', function(err, cards) {
  // asynchronously called
});

{
  "object": "list",
  "url": "/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/cards",
  "has_more": false,
  "data": [
    {
    "id": "card_103uVy2eZvKYlo2CjKliwa3N",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 4,
    "exp_year": 2017,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "country": "US",
    "name": null,
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "cvc_check": null,
    "address_line1_check": null,
    "address_zip_check": null
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/cards",
  "data": [
    #<Stripe::Card id=card_103uVy2eZvKYlo2CjKliwa3N 0x00000a> JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
},
    #<Stripe::Card[...] ...>,
    #<Stripe::Card[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/cards",
  has_more: false,
  data: [
    <Card card  id=card_103uVy2eZvKYlo2CjKliwa3N at 0x00000a> JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
},
    <stripe.Card[...] ...>,
    <stripe.Card[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/cards",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
}
    [1] => <Stripe_Card[...] ...>
    [2] => <Stripe_Card[...] ...>
  )
)
#<com.stripe.model.CardCollection id=#> JSON: {
  "data": [
    com.stripe.model.Card JSON: {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
},
    #<com.stripe.model.Card[...] ...>,
    #<com.stripe.model.Card[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/cards",
  "has_more": false,
  "data": [
    {
  "id": "card_103uVy2eZvKYlo2CjKliwa3N",
  "object": "card",
  "last4": "4242",
  "type": "Visa",
  "exp_month": 4,
  "exp_year": 2017,
  "fingerprint": "Xt5EWLLDS7FJjR1c",
  "customer": null,
  "country": "US",
  "name": null,
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "cvc_check": null,
  "address_line1_check": null,
  "address_zip_check": null
},
    {...},
    {...}
  ]
}

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). After receiving updated card details from a customer, you may choose to reopen and pay their closed invoices.
application_fee_percent: decimal A positive decimal that represents the fee percentage of the subscription invoice amount that will be transferred to the application owner’s Stripe account each billing period.
canceled_at: timestamp If the subscription has been canceled, the date of that cancellation. If the subscription was canceled with cancel_at_period_end, canceled_at will still reflect the date of the initial cancellation request, not the end of the subscription period when the subscription is automatically moved to a canceled state.
current_period_end: timestamp End of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.
current_period_start: timestamp Start of the current period that the subscription has been invoiced for
discount: hash, discount object Describes the current discount applied to this subscription, if there is one. When billing, a discount applied to a subscription overrides a discount applied on a customer-wide basis.
ended_at: timestamp If the subscription has ended (either because it was canceled or because the customer was switched to a subscription to a new plan), the date the subscription ended
trial_end: timestamp If the subscription has a trial, the end of that trial.
trial_start: timestamp If the subscription has a trial, the beginning of that trial.

{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}#<Stripe::StripeObject id=sub_3uW0zDCwSzPzqp 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}<StripeObject subscription  id=sub_3uW0zDCwSzPzqp at 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}com.stripe.model.StripeObject JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}

Creating a new subscription

Creates a new subscription on an existing customer.

Arguments

plan

required The identifier of the plan to subscribe the customer to.

coupon

optional, default is nullnilNonenullnullnull The code of the coupon to apply to this subscription. A coupon applied to a subscription will only affect invoices created for that particular subscription.

trial_end

optional, default is nullnilNonenullnullnull UTC integer timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately.

card

optional, default is nullnilNonenullnullnull The card can either be a token, like the ones returned by our Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobject containing a user's credit card details (with the options shown below). You must provide a card if the customer does not already have a valid card attached, and you are subscribing the customer for a plan that is not free. Passing card will create a new card, make it the customer default card, and delete the old customer default if one exists. If you want to add an additional card to use with subscriptions, instead use the card creation API to add the card and then the customer update API to set it as the default. Whenever you attach a card to a customer, Stripe will automatically validate the card.

numbernumbernumbernumbernumbernumber: required The card number, as a string without any separators.
exp_monthexp_monthexp_monthexp_monthexp_monthexp_month: required Two digit number representing the card's expiration month.
exp_yearexp_yearexp_yearexp_yearexp_yearexp_year: required Two or four digit number representing the card's expiration year.
cvccvccvccvccvccvc: optional, highly recommended Card security code.
namenamenamenamenamename: optional Cardholder's full name.
address_line1address_line1address_line1address_line1address_line1address_line1: optional
address_line2address_line2address_line2address_line2address_line2address_line2: optional
address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip: optional
address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state: optional
address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country: optional

quantity

optional, default is 111111 The quantity you'd like to apply to the subscription you're creating. For example, if your plan is $10/user/month, and your customer has 5 users, you could pass 5 as the quantity to have the customer charged $50 (5 x $10) monthly. If you update a subscription but don't change the plan ID (e.g. changing only the trial_end), the subscription will inherit the old subscription's quantity attribute unless you pass a new quantity parameter. If you update a subscription and change the plan ID, the new subscription will not inherit the quantity attribute and will default to 1 unless you pass a quantity parameter.

application_fee_percent

optional, default is nullnilNonenullnullnull A positive decimal (with at most two decimal places) between 1 and 100 that represents the percentage of the subscription invoice amount due each billing period (including any bundled invoice items) that will be transferred to the application owner’s Stripe account. The request must be made with an OAuth key in order to set an application fee percentage . For more information, see the application fees documentation.

Returns

The newly created subscription object if the call succeeded.

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

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptionscustomer = Stripe::Customer.retrieve({CUSTOMER_ID})
customer.subscriptions.create({:plan => PLAN_ID})
customer = stripe.Customer.retrieve({CUSTOMER_ID})
customer.subscriptions.create(plan={PLAN_ID})
$customer = Stripe_Customer::retrieve({CUSTOMER_ID});
$customer.subscriptions->create(array("plan" => {PLAN_ID}));
Customer cu = Customer.retrieve({CUSTOMER_ID});
Map params = new HashMap();
params.put("plan", {PLAN_ID});
cu.subscriptions->create(params);
stripe.customers.createSubscription({CUSTOMER_ID}, {
  plan: {PLAN_ID}
});

curl https://api.stripe.com/v1/customers/cus_3uVyE6e5atTTQE/subscriptions \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d plan=basicrequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

customer = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
customer.subscriptions.create(plan="basic")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$cu->subscriptions->create(array("plan" => "basic"));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

stripe.customers.createSubscription(
  "cus_3uVyE6e5atTTQE",
  {plan: "basic"},
  function(err, subscription) {
    // asynchronously called
  }
);

{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}#<Stripe::StripeObject id=sub_3uW0zDCwSzPzqp 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}<StripeObject subscription  id=sub_3uW0zDCwSzPzqp at 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}com.stripe.model.StripeObject JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}

Retrieving a customer's subscription

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

Arguments

id: required ID of subscription to retrieve.
customer: required

Returns

Returns the subscription object.

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID})
subscription = customer.subscriptions.retrieve({SUBSCRIPTION_ID})
customer = stripe.Customer.retrieve({CUSTOMER_ID})
subscription = customer.subscriptions.retrieve({SUBSCRIPTION_ID})
$customer = Stripe_Customer::retrieve({CUSTOMER_ID});
$subscription = $customer->subscriptions->retrieve({SUBSCRIPTION_ID}));
Customer cu = Customer.retrieve({CUSTOMER_ID});
Subscription subscription = cu.subscriptions->retrieve({SUBSCRIPTION_ID});
stripe.customers.retrieveSubscription(
  {CUSTOMER_ID},
  {SUBSCRIPTION_ID},
  function(subscription) {...}
);

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

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

customer = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
subscription = customer.subscriptions.retrieve("sub_3uW0zDCwSzPzqp")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$subscription = $cu->subscriptions->retrieve("sub_3uW0zDCwSzPzqp");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}#<Stripe::StripeObject id=sub_3uW0zDCwSzPzqp 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}<StripeObject subscription  id=sub_3uW0zDCwSzPzqp at 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}com.stripe.model.StripeObject JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}

Updating a Subscription

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

Arguments

plan

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

coupon

optional, default is nullnilNonenullnullnull The code of the coupon to apply to the customer if you would like to apply it at the same time as creating the subscription.

prorate

optional, default is true Flag telling us whether to prorate switching plans during a billing cycle.

trial_end

optional, default is nullnilNonenullnullnull UTC integer timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately.

card

optional, default is nullnilNonenullnullnull The card can either be a token, like the ones returned by our Stripe.js, or a dictionaryhashdictionaryassociative arrayMapobject containing a user's credit card details (with the options shown below). You must provide a card if the customer does not already have a valid card attached, and you are subscribing the customer for a plan that is not free. Passing card will create a new card, make it the customer default card, and delete the old customer default if one exists. If you want to add an additional card to use with subscriptions, instead use the card creation API to add the card and then the customer update API to set it as the default. Whenever you attach a card to a customer, Stripe will automatically validate the card.

numbernumbernumbernumbernumbernumber: required The card number, as a string without any separators.
exp_monthexp_monthexp_monthexp_monthexp_monthexp_month: required Two digit number representing the card's expiration month.
exp_yearexp_yearexp_yearexp_yearexp_yearexp_year: required Two or four digit number representing the card's expiration year.
cvccvccvccvccvccvc: optional, highly recommended Card security code.
namenamenamenamenamename: optional Cardholder's full name.
address_line1address_line1address_line1address_line1address_line1address_line1: optional
address_line2address_line2address_line2address_line2address_line2address_line2: optional
address_zipaddress_zipaddress_zipaddress_zipaddress_zipaddress_zip: optional
address_stateaddress_stateaddress_stateaddress_stateaddress_stateaddress_state: optional
address_countryaddress_countryaddress_countryaddress_countryaddress_countryaddress_country: optional

quantity

optional, default is 111111 The quantity you'd like to apply to the subscription you're updating. For example, if your plan is $10/user/month, and your customer has 5 users, you could pass 5 as the quantity to have the customer charged $50 (5 x $10) monthly. If you update a subscription but don't change the plan ID (e.g. changing only the trial_end), the subscription will inherit the old subscription's quantity attribute unless you pass a new quantity parameter. If you update a subscription and change the plan ID, the new subscription will not inherit the quantity attribute and will default to 1 unless you pass a quantity parameter.

application_fee_percent

optional, default is nullnilNonenullnullnull A positive decimal (with at most two decimal places) between 1 and 100 that represents the percentage of the subscription invoice amount due each billing period (including any bundled invoice items) that will be transferred to the application owner’s Stripe account. The request must be made with an OAuth key in order to set an application fee percentage . For more information, see the application fees documentation.

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

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

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

Returns

The newly created subscription object if the call succeeded.

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

POST https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID})
subscription = customer.subscriptions.retrieve({SUBSCRIPTION_ID})
subscription.plan = {PLAN_ID}
subscription.save
customer = stripe.Customer.retrieve({CUSTOMER_ID})
subscription = customer.subscriptions.retrieve({SUBSCRIPTION_ID})
subscription.plan = {PLAN_ID}
subscription.save()
$customer = Stripe_Customer::retrieve({CUSTOMER_ID});
$subscription = $customer->subscriptions->retrieve({SUBSCRIPTION_ID}));
$subscription->plan = {PLAN_ID};
$subscription->save();
Customer cu = Customer.retrieve({CUSTOMER_ID});
Subscription subscription = cu.subscriptions->retrieve({SUBSCRIPTION_ID});
Map updateParams = new HashMap();
updateParams.put("plan", {PLAN_ID});
subscription.update(updateParams);
stripe.customers.updateSubscription({CUSTOMER_ID}, {SUBSCRIPTION_ID}, {
  plan: {PLAN_ID}
})

curl https://api.stripe.com/v1/customers/cus_3uVyE6e5atTTQE/subscriptions/sub_3uW0zDCwSzPzqp \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d plan=basicrequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = Stripe::Customer.retrieve("cus_3uVyE6e5atTTQE")
subscription = customer.subscriptions.retrieve("sub_3uW0zDCwSzPzqp")
subscription.plan = "basic"
subscription.saveimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

customer = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
subscription = customer.subscriptions.retrieve("sub_3uW0zDCwSzPzqp")
subscription.plan = "basic"
subscription.save()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$subscription = $cu->subscriptions->retrieve("sub_3uW0zDCwSzPzqp");
$subscription->plan = "basic";
$subscription->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

stripe.customers.updateSubscription(
  "cus_3uVyE6e5atTTQE",
  "sub_3uW0zDCwSzPzqp",
  { plan: "basic" },
  function(err, subscription) {
    // asynchronously called
  }
);

{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}#<Stripe::StripeObject id=sub_3uW0zDCwSzPzqp 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}<StripeObject subscription  id=sub_3uW0zDCwSzPzqp at 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}com.stripe.model.StripeObject JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}

Canceling a Customer's Subscription

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

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

Arguments

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

Returns

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

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}customer = Stripe::Customer.retrieve({CUSTOMER_ID})
customer.subscriptions.retrieve({SUBSCRIPTION_ID}).delete()
customer = stripe.Customer.retrieve({CUSTOMER_ID})
customer.subscriptions.retrieve({SUBSCRIPTION_ID}).delete()
$customer = Stripe_Customer::retrieve({CUSTOMER_ID});
$customer->subscriptions->retrieve({SUBSCRIPTION_ID})->cancel();
Customer cu = Customer.retrieve({CUSTOMER_ID});
for(Subscription subscription : cu.getSubscriptions().getData()){
  if(subscription.getId().equals({SUBSCRIPTION_ID})){
    subscription.cancel(null);
    break;
  }
}
stripe.customers.cancelSubscription({CUSTOMER_ID}, {SUBSCRIPTION_ID})

curl https://api.stripe.com/v1/customers/cus_3uVyE6e5atTTQE/subscriptions/sub_3uW0zDCwSzPzqp \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETErequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

customer = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
customer.subscriptions.retrieve("sub_3uW0zDCwSzPzqp").delete()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$cu->subscriptions->retrieve("sub_3uW0zDCwSzPzqp")->cancel();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}#<Stripe::StripeObject id=sub_3uW0zDCwSzPzqp 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}<StripeObject subscription  id=sub_3uW0zDCwSzPzqp at 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}com.stripe.model.Deletedsubscription JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "deletedsubscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}{
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": "basic",
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}

Listing subscriptions

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

Arguments

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

Returns

Returns a list of the customer's active subscriptions.

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

GET https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptionsStripe::Customer.retrieve({CUSTOMER_ID}).subscriptions.all()stripe.Customer.retrieve({CUSTOMER_ID}).subscriptions.all()Stripe_Customer::retrieve({CUSTOMER_ID})->subscriptions->all();Customer.retrieve({CUSTOMER_ID}).getSubscriptions().all();stripe.customers.listSubscriptions({CUSTOMER_ID});

curl https://api.stripe.com/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/subscriptions?count=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

stripe.Customer.retrieve("cu_103uVy2eZvKYlo2CxtIYScP2").subscriptions.all(
  count=3)require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Customer::retrieve("cu_103uVy2eZvKYlo2CxtIYScP2")->subscriptions->all(array(
  'count'=>3));Customer cu = Customer.retrieve("cu_103uVy2eZvKYlo2CxtIYScP2");
Map subscriptionParams = new HashMap();
subscriptionParams.put("count", 3);
CustomerSubscriptionCollection subscriptions = cu.getSubscriptions().all(subscriptionParams);
stripe.customers.listSubscriptions('cu_103uVy2eZvKYlo2CxtIYScP2', function(err, subscriptions) {
  // asynchronously called
});

{
  "object": "list",
  "url": "/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/subscriptions",
  "has_more": false,
  "data": [
    {
    "id": "sub_3uW0zDCwSzPzqp",
    "plan": {
      "interval": "month",
      "name": "New plan name",
      "created": 1386247539,
      "amount": 2000,
      "currency": "usd",
      "id": "gold21323",
      "object": "plan",
      "livemode": false,
      "interval_count": 1,
      "trial_period_days": null,
      "metadata": {
      },
      "statement_description": null
    },
    "object": "subscription",
    "start": 1398323301,
    "status": "active",
    "customer": "cus_3uVyE6e5atTTQE",
    "cancel_at_period_end": false,
    "current_period_start": 1398323301,
    "current_period_end": 1400915301,
    "ended_at": null,
    "trial_start": null,
    "trial_end": null,
    "canceled_at": null,
    "quantity": 1,
    "application_fee_percent": null,
    "discount": null
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/subscriptions",
  "data": [
    #<Stripe::StripeObject id=sub_3uW0zDCwSzPzqp 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
},
    #<Stripe::Subscription[...] ...>,
    #<Stripe::Subscription[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/subscriptions",
  has_more: false,
  data: [
    <StripeObject subscription  id=sub_3uW0zDCwSzPzqp at 0x00000a> JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
},
    <stripe.Subscription[...] ...>,
    <stripe.Subscription[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/subscriptions",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
}
    [1] => <Stripe_Subscription[...] ...>
    [2] => <Stripe_Subscription[...] ...>
  )
)
#<com.stripe.model.SubscriptionCollection id=#> JSON: {
  "data": [
    com.stripe.model.StripeObject JSON: {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
},
    #<com.stripe.model.Subscription[...] ...>,
    #<com.stripe.model.Subscription[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/customers/cu_103uVy2eZvKYlo2CxtIYScP2/subscriptions",
  "has_more": false,
  "data": [
    {
  "id": "sub_3uW0zDCwSzPzqp",
  "plan": {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
  "object": "subscription",
  "start": 1398323301,
  "status": "active",
  "customer": "cus_3uVyE6e5atTTQE",
  "cancel_at_period_end": false,
  "current_period_start": 1398323301,
  "current_period_end": 1400915301,
  "ended_at": null,
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "quantity": 1,
  "application_fee_percent": null,
  "discount": null
},
    {...},
    {...}
  ]
}

Plans

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

The plan object

Attributes

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

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

Creating plans

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

Arguments

id: required Unique string of your choice that will be used to identify this plan when subscribing a customer. This could be an identifier like "gold" or a primary key from your own database.
amount: required A positive integer in cents (or 0 for a free plan) representing how much to charge (on a recurring basis).
currency: required 3-letter ISO code for currency.
interval: required Specifies billing frequency. Either week, month or year.
interval_count: optional, default is 1 The number of intervals between each subscription billing. For example, interval=month and interval_count=3 bills every 3 months. Maximum of one year interval allowed (1 year, 12 months, or 52 weeks).
name: required Name of the plan, to be displayed on invoices and in the web interface.
trial_period_days: optional Specifies a trial period in (an integer number of) days. If you include a trial period, the customer won't be billed for the first time until the trial period ends. If the customer cancels before the trial period is over, she'll never be billed at all.
metadata: optional, default is { }{ }{ }{ }{ }{ } A set of key/value pairs that you can attach to a plan object. It can be useful for storing additional information about the plan in a structured format.
statement_description: optional, default is nullnilNonenullnullnull An arbitrary string to be displayed on your customers' credit card statements (alongside your company name) for charges created by this plan. This may be up to 15 characters. As an example, if your website is RunClub and you specify Silver Plan, the user will see RUNCLUB SILVER PLAN. The statement description may not include <>"' characters. While most banks display this information consistently, some may display it incorrectly or not at all.

POST https://api.stripe.com/v1/plansStripe::Plan.createstripe.Plan.create()Stripe_Plan::create();Plan.create();stripe.plans.create();

curl https://api.stripe.com/v1/plans \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=2000 \
   -d interval=month \
   -d "name=Amazing Gold Plan" \
   -d currency=usd \
   -d id=goldrequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Plan.create(
  :amount => 2000,
  :interval => 'month',
  :name => 'Amazing Gold Plan',
  :currency => 'usd',
  :id => 'gold'
)import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Plan.create(
  amount=2000,
  interval='month',
  name='Amazing Gold Plan',
  currency='usd',
  id='gold')require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Plan::create(array(
  "amount" => 2000,
  "interval" => "month",
  "name" => "Amazing Gold Plan",
  "currency" => "usd",
  "id" => "gold")
);Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> planParams = new HashMap<String, Object>();
planParams.put("amount", 2000);
planParams.put("interval", "month");
planParams.put("name", "Amazing Gold Plan");
planParams.put("currency", "usd");
planParams.put("id", "gold");

Plan.create(planParams);var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.plans.create({
  amount: 2000,
  interval: "month",
  name: "Amazing Gold Plan",
  currency: "usd",
  id: "gold"
}, function(err, plan) {
  // asynchronously called
});

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

Retrieving a Plan

Retrieves the plan with the given ID.

Arguments

id: required The ID of the desired plan.

Returns

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

GET https://api.stripe.com/v1/plans/{PLAN_ID}Stripe::Plan.retrieve({PLAN_ID})stripe.Plan.retrieve({PLAN_ID})Stripe_Plan::retrieve({PLAN_ID});Plan.retrieve({PLAN_ID});stripe.plans.retrieve({PLAN_ID});

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

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

stripe.Plan.retrieve("gold21323")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

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

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

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

Updating a plan

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

Arguments

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

Returns

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

POST https://api.stripe.com/v1/plans/{PLAN_ID}p = Stripe::Plan.retrieve({PLAN_ID})
p.name = {NAME}
...
p.save
p = stripe.Plan.retrieve({PLAN_ID})
p.name = {NAME}
...
p.save()
$p = Stripe_Plan::retrieve({PLAN_ID});
$p->name = {NAME};
...
$p->save();
Plan p = Plan.retrieve({PLAN_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("name", {NAME});
...
p.update(updateParams);stripe.plans.update({PLAN_ID}, {
  name: {NAME}
});

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

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

p = stripe.Plan.retrieve("gold21323")
p.name = "New plan name"
p.save()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

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

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

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

Deleting a plan

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

Arguments

id: required The identifier of the plan to be deleted.

Returns

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

DELETE https://api.stripe.com/v1/plans/{PLAN_ID}plan = Stripe::Plan.retrieve({PLAN_ID})
plan.delete
plan = stripe.Plan.retrieve({PLAN_ID})
plan.delete()
$plan = Stripe_Plan::retrieve({PLAN_ID});
$plan->delete();
Plan plan = Plan.retrieve({PLAN_ID});
plan.delete();
stripe.plans.del({PLAN_ID});

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

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

plan = stripe.Plan.retrieve("gold21323")
plan.delete()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

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

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

{
  "deleted": true,
  "id": "gold21323"
}#<Stripe::Object id=gold21323 0x00000a> JSON: {
  "deleted": true,
  "id": "gold21323"
}<Object object  id=gold21323 at 0x00000a> JSON: {
  "deleted": true,
  "id": "gold21323"
}{
  "deleted": true,
  "id": "gold21323"
}com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "gold21323"
}{
  "deleted": true,
  "id": "gold21323"
}

List all Plans

Returns a list of your plans.

Arguments

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

Returns

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

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

GET https://api.stripe.com/v1/plansStripe::Plan.allstripe.Plan.all()Stripe_Plan::all();Plan.all(Map options);stripe.plans.list();

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

Stripe::Plan.allimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Plan.all()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Plan::all();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Plan.all(new HashMap<String, Object>());var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

{
  "object": "list",
  "url": "/v1/plans",
  "has_more": false,
  "data": [
    {
    "interval": "month",
    "name": "New plan name",
    "created": 1386247539,
    "amount": 2000,
    "currency": "usd",
    "id": "gold21323",
    "object": "plan",
    "livemode": false,
    "interval_count": 1,
    "trial_period_days": null,
    "metadata": {
    },
    "statement_description": null
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "/v1/plans",
  "data": [
    #<Stripe::Plan id=gold21323 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_description": null
},
    #<Stripe::Plan[...] ...>,
    #<Stripe::Plan[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/plans",
  has_more: false,
  data: [
    <Plan plan  id=gold21323 at 0x00000a> JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_description": null
},
    <stripe.Plan[...] ...>,
    <stripe.Plan[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "/v1/plans",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_description": null
}
    [1] => <Stripe_Plan[...] ...>
    [2] => <Stripe_Plan[...] ...>
  )
)
#<com.stripe.model.PlanCollection id=#> JSON: {
  "data": [
    com.stripe.model.Plan JSON: {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_description": null
},
    #<com.stripe.model.Plan[...] ...>,
    #<com.stripe.model.Plan[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/plans",
  "has_more": false,
  "data": [
    {
  "interval": "month",
  "name": "New plan name",
  "created": 1386247539,
  "amount": 2000,
  "currency": "usd",
  "id": "gold21323",
  "object": "plan",
  "livemode": false,
  "interval_count": 1,
  "trial_period_days": null,
  "metadata": {
  },
  "statement_description": null
},
    {...},
    {...}
  ]
}

Coupons

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

The coupon object

Attributes

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

{
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}#<Stripe::Coupon id=50-pc-forever-once 0x00000a> JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}<Coupon coupon  id=50-pc-forever-once at 0x00000a> JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}{
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}com.stripe.model.Coupon JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}{
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}

Creating coupons

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

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

Arguments

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

Returns

Returns the coupon object.

POST https://api.stripe.com/v1/couponsStripe::Coupon.createstripe.Coupon.create()Stripe_Coupon::create();Coupon.create();stripe.coupons.create();

curl https://api.stripe.com/v1/coupons \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d percent_off=25 \
   -d duration=repeating \
   -d duration_in_months=3 \
   -d id=25OFFrequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Coupon.create(
  :percent_off => 25,
  :duration => 'repeating',
  :duration_in_months => 3,
  :id => '25OFF'
)import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Coupon.create(
  percent_off=25,
  duration='repeating',
  duration_in_months=3,
  id='25OFF')require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Coupon::create(array(
  "percent_off" => 25,
  "duration" => "repeating",
  "duration_in_months" => 3,
  "id" => "25OFF")
);Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> couponParams = new HashMap<String, Object>();
couponParams.put("percent_off", 25);
couponParams.put("duration", "repeating");
couponParams.put("duration_in_months", 3);
couponParams.put("id", "25OFF");

Coupon.create(couponParams);var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.create({
  percent_off: 25,
  duration: 'repeating',
  duration_in_months: 3,
  id: '25OFF'
});

{
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}#<Stripe::Coupon id=50-pc-forever-once 0x00000a> JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}<Coupon coupon  id=50-pc-forever-once at 0x00000a> JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}{
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}com.stripe.model.Coupon JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}{
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}

Retrieving a Coupon

Retrieves the coupon with the given ID.

Arguments

id: required The ID of the desired coupon.

Returns

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

GET https://api.stripe.com/v1/coupons/{COUPON_ID}Stripe::Coupon.retrieve({COUPON_ID})stripe.Coupon.retrieve({COUPON_ID})Stripe_Coupon::retrieve({COUPON_ID});Coupon.retrieve({COUPON_ID});stripe.coupons.retrieve({COUPON_ID});

curl https://api.stripe.com/v1/coupons/50-pc-forever-once \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Coupon.retrieve("50-pc-forever-once")import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Coupon.retrieve("50-pc-forever-once")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Coupon::retrieve("50-pc-forever-once");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon.retrieve("50-pc-forever-once");var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.retrieve("50-pc-forever-once", function(err, coupon) {
  // asynchronously called
});

{
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}#<Stripe::Coupon id=50-pc-forever-once 0x00000a> JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}<Coupon coupon  id=50-pc-forever-once at 0x00000a> JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}{
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}com.stripe.model.Coupon JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}{
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}

Deleting a coupon

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

Arguments

id: required The identifier of the coupon to be deleted.

Returns

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

DELETE https://api.stripe.com/v1/coupons/{COUPON_ID}cpn = Stripe::Coupon.retrieve({COUPON_ID})
cpn.delete
cpn = stripe.Coupon.retrieve({COUPON_ID})
cpn.delete()
$cpn = Stripe_Coupon::retrieve({COUPON_ID});
$cpn->delete();
Coupon cpn = Coupon.retrieve({COUPON_ID});
cpn.delete();
stripe.coupons.del({COUPON_ID})

curl https://api.stripe.com/v1/coupons/50-pc-forever-once \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETErequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cpn = Stripe::Coupon.retrieve("50-pc-forever-once")
cpn.deleteimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cpn = stripe.Coupon.retrieve("50-pc-forever-once")
cpn.delete()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cpn = Stripe_Coupon::retrieve("50-pc-forever-once");
$cpn->delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon cpn = Coupon.retrieve("50-pc-forever-once");
cpn.delete();var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.del("50-pc-forever-once")

{
  "deleted": true,
  "id": "50-pc-forever-once"
}#<Stripe::Object id=50-pc-forever-once 0x00000a> JSON: {
  "deleted": true,
  "id": "50-pc-forever-once"
}<Object object  id=50-pc-forever-once at 0x00000a> JSON: {
  "deleted": true,
  "id": "50-pc-forever-once"
}{
  "deleted": true,
  "id": "50-pc-forever-once"
}com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "50-pc-forever-once"
}{
  "deleted": true,
  "id": "50-pc-forever-once"
}

List all Coupons

Returns a list of your coupons.

Arguments

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

Returns

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

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

GET https://api.stripe.com/v1/couponsStripe::Coupon.allstripe.Coupon.all()Stripe_Coupon::all();Coupon.all(Map options);stripe.coupons.list();

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

Stripe::Coupon.allimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Coupon.all()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Coupon::all();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Coupon.all(new HashMap<String, Object>());var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.coupons.list();

{
  "object": "list",
  "url": "/v1/coupons",
  "has_more": false,
  "data": [
    {
    "id": "50-pc-forever-once",
    "created": 1397741615,
    "percent_off": 50,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": 1397748842,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
    }
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "/v1/coupons",
  "data": [
    #<Stripe::Coupon id=50-pc-forever-once 0x00000a> JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
},
    #<Stripe::Coupon[...] ...>,
    #<Stripe::Coupon[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/coupons",
  has_more: false,
  data: [
    <Coupon coupon  id=50-pc-forever-once at 0x00000a> JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
},
    <stripe.Coupon[...] ...>,
    <stripe.Coupon[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "/v1/coupons",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
}
    [1] => <Stripe_Coupon[...] ...>
    [2] => <Stripe_Coupon[...] ...>
  )
)
#<com.stripe.model.CouponCollection id=#> JSON: {
  "data": [
    com.stripe.model.Coupon JSON: {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
},
    #<com.stripe.model.Coupon[...] ...>,
    #<com.stripe.model.Coupon[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/coupons",
  "has_more": false,
  "data": [
    {
  "id": "50-pc-forever-once",
  "created": 1397741615,
  "percent_off": 50,
  "amount_off": null,
  "currency": "usd",
  "object": "coupon",
  "livemode": false,
  "duration": "forever",
  "redeem_by": 1397748842,
  "max_redemptions": null,
  "times_redeemed": 0,
  "duration_in_months": null,
  "valid": false,
  "metadata": {
  }
},
    {...},
    {...}
  ]
}

Discounts

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

The discount object

Attributes

object: string, value is "discount"
coupon: hash, coupon object Hash describing the coupon applied to create this discount
customer: 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": "50-pc-forever-once",
    "created": 1397741615,
    "percent_off": 50,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": 1397748842,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
    }
  },
  "start": 1391694761,
  "object": "discount",
  "customer": "cus_3uVyE6e5atTTQE",
  "subscription": null,
  "end": 1399384361
}#<Stripe::Discount 0x00000a> JSON: {
  "coupon": {
    "id": "50-pc-forever-once",
    "created": 1397741615,
    "percent_off": 50,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": 1397748842,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
    }
  },
  "start": 1391694761,
  "object": "discount",
  "customer": "cus_3uVyE6e5atTTQE",
  "subscription": null,
  "end": 1399384361
}<Discount discount  at 0x00000a> JSON: {
  "coupon": {
    "id": "50-pc-forever-once",
    "created": 1397741615,
    "percent_off": 50,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": 1397748842,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
    }
  },
  "start": 1391694761,
  "object": "discount",
  "customer": "cus_3uVyE6e5atTTQE",
  "subscription": null,
  "end": 1399384361
}{
  "coupon": {
    "id": "50-pc-forever-once",
    "created": 1397741615,
    "percent_off": 50,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": 1397748842,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
    }
  },
  "start": 1391694761,
  "object": "discount",
  "customer": "cus_3uVyE6e5atTTQE",
  "subscription": null,
  "end": 1399384361
}com.stripe.model.Discount JSON: {
  "coupon": {
    "id": "50-pc-forever-once",
    "created": 1397741615,
    "percent_off": 50,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": 1397748842,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
    }
  },
  "start": 1391694761,
  "object": "discount",
  "customer": "cus_3uVyE6e5atTTQE",
  "subscription": null,
  "end": 1399384361
}{
  "coupon": {
    "id": "50-pc-forever-once",
    "created": 1397741615,
    "percent_off": 50,
    "amount_off": null,
    "currency": "usd",
    "object": "coupon",
    "livemode": false,
    "duration": "forever",
    "redeem_by": 1397748842,
    "max_redemptions": null,
    "times_redeemed": 0,
    "duration_in_months": null,
    "valid": false,
    "metadata": {
    }
  },
  "start": 1391694761,
  "object": "discount",
  "customer": "cus_3uVyE6e5atTTQE",
  "subscription": null,
  "end": 1399384361
}

Deleting a Customer-wide Discount

Removes the currently applied discount on a customer.

Returns

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

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/discountcu = Stripe::Customer.retrieve({CUSTOMER_ID})
cu.delete_discount
cu = stripe.Customer.retrieve({CUSTOMER_ID})
cu.delete_discount()
$cu = Stripe_Customer::retrieve({CUSTOMER_ID});
$cu->deleteDiscount();
Customer cu = Customer.retrieve({CUSTOMER_ID});
cu.deleteDiscount();
stripe.customers.deleteDiscount({CUSTOMER_ID});

curl https://api.stripe.com/v1/customers/cus_3uVyE6e5atTTQE/discount \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETErequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = Stripe::Customer.retrieve("cus_3uVyE6e5atTTQE")
cu.delete_discountimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

cu = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
cu.delete_discount()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$cu->deleteDiscount();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_3uVyE6e5atTTQE");
cu.deleteDiscount();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

{
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}#<Stripe::Object id=di_103Rm82eZvKYlo2CH0he3vGX 0x00000a> JSON: {
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}<Object object  id=di_103Rm82eZvKYlo2CH0he3vGX at 0x00000a> JSON: {
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}{
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}{
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}

Deleting a Subscription Discount

Removes the currently applied discount on a subscription.

Returns

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

DELETE https://api.stripe.com/v1/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}/discountcu = Stripe::Customer.retrieve({CUSTOMER_ID})
cu.subscriptions.retrieve({SUBSCRIPTION_ID}).delete_discount()
cu = stripe.Customer.retrieve({CUSTOMER_ID})
cu.subscriptions.retrieve({SUBSCRIPTION_ID}).delete_discount()
$cu = Stripe_Customer::retrieve({CUSTOMER_ID});
$cu->subscriptions->retrieve({SUBSCRIPTION_ID})->deleteDiscount();
Customer cu = Customer.retrieve({CUSTOMER_ID});
cu.subscriptions.retrieve({SUBSCRIPTION_ID}).deleteDiscount();
stripe.customers.deleteSubscriptionDiscount({CUSTOMER_ID}, {SUBSCRIPTION_ID});

curl https://api.stripe.com/v1/customers/cus_3uVyE6e5atTTQE/subscriptions/sub_3uW0zDCwSzPzqp/discount \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETErequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

cu = stripe.Customer.retrieve("cus_3uVyE6e5atTTQE")
cu.subscriptions.retrieve("sub_3uW0zDCwSzPzqp").delete_discount()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$cu = Stripe_Customer::retrieve("cus_3uVyE6e5atTTQE");
$cu->subscriptions->retrieve("sub_3uW0zDCwSzPzqp")->deleteDiscount();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Customer cu = Customer.retrieve("cus_3uVyE6e5atTTQE");
cu.subscriptions.retrieve("sub_3uW0zDCwSzPzqp").deleteDiscount();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

{
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}#<Stripe::Object id=di_103Rm82eZvKYlo2CH0he3vGX 0x00000a> JSON: {
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}<Object object  id=di_103Rm82eZvKYlo2CH0he3vGX at 0x00000a> JSON: {
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}{
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}{
  "deleted": true,
  "id": "di_103Rm82eZvKYlo2CH0he3vGX"
}

Invoices

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

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

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

The invoice object

Attributes

id

string

object

string, value is "invoice"

livemode

boolean

amount_due

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

attempt_count

positive integer or zero Number of automatic payment attempts made for this invoice. Does not include manual attempts to pay the invoice.

attempted

boolean Whether or not an attempt has been made to pay the invoice. An invoice is not attempted until 1 hour after the invoice.created webhook, for example, so you might not want to display that invoice as unpaid to your users.

closed

boolean Whether or not the invoice is still trying to collect payment. An invoice is closed if it’s either paid or it has been marked closed. A closed invoice will no longer attempt to collect payment.

currency

currency

customer

string

date

timestamp

lines

list The individual line items that make up the invoice

object: string 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 or null 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 the invoice covers

period_start

timestamp Start of the usage period the invoice covers

starting_balance

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

subtotal

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

total

integer Total after discount

application_fee

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

charge

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

subscription

string The subscription that this invoice was prepared for, if any.

metadata

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

{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}#<Stripe::Invoice id=in_103uVy2eZvKYlo2CLlWNNuV7 0x00000a> JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}<Invoice invoice  id=in_103uVy2eZvKYlo2CLlWNNuV7 at 0x00000a> JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}com.stripe.model.Invoice JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}

The invoice_line_item object

Attributes

id: string The ID of the source of this line item, either an invoice item or a subscription
object: string line_item
livemode: boolean Whether or not this is a test line item
amount: integer The amount, in cents
currency: currency
period: hash The period this line_item covers
proration: boolean Whether or not this is a proration
type: string A string identifying the type of the source of this line item, either an invoice item or a subscription
description: string A text description of the line item, if the line item is an invoice item
metadata: metadata hash Key-value pairs attached to the line item, if the line item is an invoice item
plan: hash, plan object The plan of the subscription, if the line item is a subscription
quantity: integer The quantity of the subscription, if the line item is a subscription

{
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
}#<Stripe::Line_item id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: {
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
}<Line_item line_item  id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: {
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
}{
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
}com.stripe.model.Line_item JSON: {
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
}{
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
}

Retrieving an Invoice

Retrieves the invoice with the given ID.

Arguments

id: required The identifier of the desired invoice.

Returns

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

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

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

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

GET https://api.stripe.com/v1/invoices/{INVOICE_ID}Stripe::Invoice.retrieve({INVOICE_ID})stripe.Invoice.retrieve({INVOICE_ID})Stripe_Invoice::retrieve({INVOICE_ID});Invoice.retrieve({INVOICE_ID});stripe.invoices.retrieve({INVOICE_ID});

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

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

stripe.Invoice.retrieve("in_103uVy2eZvKYlo2CLlWNNuV7")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Invoice::retrieve("in_103uVy2eZvKYlo2CLlWNNuV7");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}

Retrieve an invoice's line items

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

Arguments

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

Returns

Returns a list of line_item objects.

GET https://api.stripe.com/v1/invoices/{INVOICE_ID}/linesStripe::Invoice.retrieve({INVOICE_ID}).lines.all()stripe.Invoice.retrieve({INVOICE_ID}).lines.all()Stripe_Invoice::retrieve({INVOICE_ID})->lines->all();Invoice.retrieve({INVOICE_ID}).getLines().all();stripe.invoices.retrieveLines({INVOICE_ID});

curl https://api.stripe.com/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines?count=5&offset=5 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Invoice.retrieve("in_103uVy2eZvKYlo2CLlWNNuV7").lines.all({
  :count => 5, :offset => 5})import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.retrieve("in_103uVy2eZvKYlo2CLlWNNuV7").lines.all(
  offset=5,
  count=5)require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Invoice::retrieve("in_103uVy2eZvKYlo2CLlWNNuV7")->lines->all(array(
  'count'=>5, 'offset'=>5));Invoice inv = Invoice.retrieve("in_103uVy2eZvKYlo2CLlWNNuV7");
Map lineParams = new HashMap();
lineParams.put("count", 5);
lineParams.put("offset", 5);
InvoiceLineItemCollection lines = inv.getLines().all(lineParams);
stripe.invoices.retrieveLines(
  "in_103uVy2eZvKYlo2CLlWNNuV7",
  { count: 5, offset: 5 },
  function(err, lines) {
    // asynchronously called
  }
);

{
  "object": "list",
  "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines",
  "has_more": false,
  "data": [
    {
    "id": "ii_103n902eZvKYlo2CfQmZCSQD",
    "object": "line_item",
    "type": "invoiceitem",
    "livemode": false,
    "amount": 1999,
    "currency": "usd",
    "proration": false,
    "period": {
      "start": 1396623292,
      "end": 1396623292
    },
    "quantity": null,
    "plan": null,
    "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
    "metadata": {
    }
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines",
  "data": [
    #<Stripe::Line_item id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: {
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
},
    #<Stripe::LineItem[...] ...>,
    #<Stripe::LineItem[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines",
  has_more: false,
  data: [
    <Line_item line_item  id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: {
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
},
    <stripe.LineItem[...] ...>,
    <stripe.LineItem[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
}
    [1] => <Stripe_LineItem[...] ...>
    [2] => <Stripe_LineItem[...] ...>
  )
)
#<com.stripe.model.InvoiceLineItemCollection id=#> JSON: {
  "data": [
    com.stripe.model.Line_item JSON: {
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
},
    #<com.stripe.model.InvoiceLineItem[...] ...>,
    #<com.stripe.model.InvoiceLineItem[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines",
  "has_more": false,
  "data": [
    {
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "object": "line_item",
  "type": "invoiceitem",
  "livemode": false,
  "amount": 1999,
  "currency": "usd",
  "proration": false,
  "period": {
    "start": 1396623292,
    "end": 1396623292
  },
  "quantity": null,
  "plan": null,
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  }
},
    {...},
    {...}
  ]
}

Creating an invoice

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

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

Arguments

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

Returns

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

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

POST https://api.stripe.com/v1/invoicesStripe::Invoice.create()
stripe.Invoice.create()
Stripe_Invoice::create();
Invoice.create();
stripe.invoices.create();

curl https://api.stripe.com/v1/invoices \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d customer=cus_3uVyE6e5atTTQErequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

stripe.Invoice.create(
    customer="cus_3uVyE6e5atTTQE"require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Invoice::create(array(
    "customer" => "cus_3uVyE6e5atTTQE"
));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

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

{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}#<Stripe::Invoice id=in_103uVy2eZvKYlo2CLlWNNuV7 0x00000a> JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}<Invoice invoice  id=in_103uVy2eZvKYlo2CLlWNNuV7 at 0x00000a> JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}com.stripe.model.Invoice JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}

Paying an invoice

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

Arguments

id: required

Returns

Returns the invoice object.

POST https://api.stripe.com/v1/invoices/{INVOICE_ID}/payinvoice = Stripe::Invoice.retrieve({INVOICE_ID})
invoice.pay
invoice = stripe.Invoice.retrieve({INVOICE_ID})
invoice.pay()
$invoice = Stripe_Invoice::retrieve({INVOICE_ID});
$invoice->pay();
invoice = Invoice.retrieve({INVOICE_ID});
invoice.pay();
stripe.invoices.pay({INVOICE_ID});

curl https://api.stripe.com/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/pay \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POSTrequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

invoice = Stripe::Invoice.retrieve("in_103uVy2eZvKYlo2CLlWNNuV7")
invoice.payimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

invoice = stripe.Invoice.retrieve("in_103uVy2eZvKYlo2CLlWNNuV7")
invoice.pay()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$invoice = Stripe_Invoice::retrieve("in_103uVy2eZvKYlo2CLlWNNuV7");
$invoice->pay();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

invoice = Invoice.retrieve("in_103uVy2eZvKYlo2CLlWNNuV7");
invoice.pay();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null,
  "last_payment_attempt": null
}#<Stripe::Invoice id=in_103uVy2eZvKYlo2CLlWNNuV7 0x00000a> JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null,
  "last_payment_attempt": null
}<Invoice invoice  id=in_103uVy2eZvKYlo2CLlWNNuV7 at 0x00000a> JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null,
  "last_payment_attempt": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null,
  "last_payment_attempt": null
}com.stripe.model.Invoice JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null,
  "last_payment_attempt": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "ii_103n902eZvKYlo2CfQmZCSQD",
        "object": "line_item",
        "type": "invoiceitem",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1396623292,
          "end": 1396623292
        },
        "quantity": null,
        "plan": null,
        "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
        "metadata": {
        }
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null,
  "last_payment_attempt": null
}

Updating an invoice

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

Arguments

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

Returns

Returns the invoice object.

POST https://api.stripe.com/v1/invoices/{INVOICE_ID}invoice = Stripe::Invoice.retrieve({INVOICE_ID})
invoice.closed = true
...
invoice.save
invoice = stripe.Invoice.retrieve({INVOICE_ID})
invoice.closed = True
...
invoice.save()
$invoice = Stripe_Invoice::retrieve({INVOICE_ID});
$invoice->closed = true;
...
$invoice->save();
Invoice invoice = Invoice.retrieve({INVOICE_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("closed", "true");
...
invoice.update(updateParams);stripe.invoices.retrieve({INVOICE_ID}, {
  closed: true,
  ...
});

curl https://api.stripe.com/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d closed=truerequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

invoice = Stripe::Invoice.retrieve("in_103uVy2eZvKYlo2CLlWNNuV7")
invoice.saveimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

invoice = stripe.Invoice.retrieve("in_103uVy2eZvKYlo2CLlWNNuV7")
invoice.closed = True
invoice.save()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$invoice = Stripe_Invoice::retrieve("in_103uVy2eZvKYlo2CLlWNNuV7");
$invoice->closed = true
$invoice->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Invoice invoice = Invoice.retrieve("in_103uVy2eZvKYlo2CLlWNNuV7");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("closed", "true");
invoice.update(updateParams);var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoices.update(
  "in_103uVy2eZvKYlo2CLlWNNuV7",
  {
    closed: true
  },
  function(err, invoice) {
    // asynchronously called
  }
)

{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}#<Stripe::Invoice id=in_103uVy2eZvKYlo2CLlWNNuV7 0x00000a> JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}<Invoice invoice  id=in_103uVy2eZvKYlo2CLlWNNuV7 at 0x00000a> JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}com.stripe.model.Invoice JSON: {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}

Retrieving a List of Invoices

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

Arguments

customer

optional The identifier of the customer whose invoices to return. If none is provided, all invoices will be returned.

date

optional A filter on the list based on the object date field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:

gtgtgtgtgtgt: optional Return values where the date field is after this timestamp.
gtegtegtegtegtegte: optional Return values where the date field is after or equal to this timestamp.
ltltltltltlt: optional Return values where the date field is before this timestamp.
ltelteltelteltelte: optional Return values where the date field is before or equal to this timestamp.

ending_before

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

limit

optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

starting_after

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

Returns

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

GET https://api.stripe.com/v1/invoicesStripe::Invoice.allstripe.Invoice.all()Stripe_Invoice::all();Invoice.all(Map options);stripe.invoices.list();

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

Stripe::Invoice.all(
  :customer => "cus_3uVyE6e5atTTQE",
  :count => 3
)import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.all(
  customer="cus_3uVyE6e5atTTQE",
  count=3)require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Invoice::all(array(
  "customer" => "cus_3uVyE6e5atTTQE",
  "count" => 3)
);Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

stripe.invoices.list(
  { customer: "cus_3uVyE6e5atTTQE", count: 3 },
  function(err, invoices) {
    // asynchronously called
  }
);

{
  "object": "list",
  "url": "/v1/invoices",
  "has_more": false,
  "data": [
    {
    "date": 1398323228,
    "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
    "period_start": 1398323228,
    "period_end": 1398323228,
    "lines": {
      "data": [
        {
          "id": "sub_3uW0zDCwSzPzqp",
          "object": "line_item",
          "type": "subscription",
          "livemode": true,
          "amount": 2000,
          "currency": "usd",
          "proration": false,
          "period": {
            "start": 1400915301,
            "end": 1403593701
          },
          "quantity": 1,
          "plan": {
            "interval": "month",
            "name": "New plan name",
            "created": 1386247539,
            "amount": 2000,
            "currency": "usd",
            "id": "gold21323",
            "object": "plan",
            "livemode": false,
            "interval_count": 1,
            "trial_period_days": null,
            "metadata": {
            },
            "statement_description": null
          },
          "description": null,
          "metadata": null
        }
      ],
      "count": 1,
      "object": "list",
      "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
    },
    "subtotal": 0,
    "total": 0,
    "customer": "cus_3uVyE6e5atTTQE",
    "object": "invoice",
    "attempted": true,
    "closed": true,
    "paid": true,
    "livemode": false,
    "attempt_count": 0,
    "amount_due": 0,
    "currency": "usd",
    "starting_balance": 0,
    "ending_balance": null,
    "next_payment_attempt": null,
    "charge": null,
    "discount": null,
    "application_fee": null,
    "subscription": "sub_3uVyZtqbGP43Gy",
    "metadata": {
    },
    "description": null
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "/v1/invoices",
  "data": [
    {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
},
    #<Stripe::Invoice[...] ...>,
    #<Stripe::Invoice[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/invoices",
  has_more: false,
  data: [
    {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
},
    <stripe.Invoice[...] ...>,
    <stripe.Invoice[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "/v1/invoices",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}
    [1] => <Stripe_Invoice[...] ...>
    [2] => <Stripe_Invoice[...] ...>
  )
)
#<com.stripe.model.InvoiceCollection id=#> JSON: {
  "data": [
    {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
},
    #<com.stripe.model.Invoice[...] ...>,
    #<com.stripe.model.Invoice[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/invoices",
  "has_more": false,
  "data": [
    {
  "date": 1398323228,
  "id": "in_103uVy2eZvKYlo2CLlWNNuV7",
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "data": [
      {
        "id": "sub_3uW0zDCwSzPzqp",
        "object": "line_item",
        "type": "subscription",
        "livemode": true,
        "amount": 2000,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1400915301,
          "end": 1403593701
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "New plan name",
          "created": 1386247539,
          "amount": 2000,
          "currency": "usd",
          "id": "gold21323",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ],
    "count": 1,
    "object": "list",
    "url": "/v1/invoices/in_103uVy2eZvKYlo2CLlWNNuV7/lines"
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
},
    {...},
    {...}
  ]
}

Retrieving a Customer's Upcoming Invoice

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

Arguments

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

Returns

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

GET https://api.stripe.com/v1/invoices/upcomingStripe::Invoice.upcoming(:customer => {CUSTOMER_ID})
stripe.Invoice.upcoming(customer={CUSTOMER_ID})
Stripe_Invoice::upcoming(array("customer" => {CUSTOMER_ID}));
Map<String, Object> invoiceParams = new HashMap<String, Object>();
invoiceParams.put("customer", {CUSTOMER_ID});
Invoice.upcoming(invoiceParams);stripe.invoices.retrieveUpcoming({CUSTOMER_ID})

curl https://api.stripe.com/v1/invoices/upcoming?customer=cus_3uVyE6e5atTTQE \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Invoice.upcoming(:customer => "cus_3uVyE6e5atTTQE")import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Invoice.upcoming(customer="cus_3uVyE6e5atTTQE")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Invoice::upcoming(array("customer" => "cus_3uVyE6e5atTTQE"));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

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

stripe.invoices.retrieveUpcoming(
  "cus_3uVyE6e5atTTQE",
  function(err, upcoming) {
    // asynchronously called
  }
);

{
  "date": 1398323228,
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/invoices/upcoming/lines?customer=cus_3uVyE6e5atTTQE",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "object": "line_item",
        "type": "subscription",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1398323228,
          "end": 1398755228
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ]
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}#<Stripe::Invoice 0x00000a> JSON: {
  "date": 1398323228,
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/invoices/upcoming/lines?customer=cus_3uVyE6e5atTTQE",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "object": "line_item",
        "type": "subscription",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1398323228,
          "end": 1398755228
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ]
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}<Invoice invoice  at 0x00000a> JSON: {
  "date": 1398323228,
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/invoices/upcoming/lines?customer=cus_3uVyE6e5atTTQE",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "object": "line_item",
        "type": "subscription",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1398323228,
          "end": 1398755228
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ]
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/invoices/upcoming/lines?customer=cus_3uVyE6e5atTTQE",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "object": "line_item",
        "type": "subscription",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1398323228,
          "end": 1398755228
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ]
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}com.stripe.model.Invoice JSON: {
  "date": 1398323228,
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/invoices/upcoming/lines?customer=cus_3uVyE6e5atTTQE",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "object": "line_item",
        "type": "subscription",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1398323228,
          "end": 1398755228
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ]
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}{
  "date": 1398323228,
  "period_start": 1398323228,
  "period_end": 1398323228,
  "lines": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/invoices/upcoming/lines?customer=cus_3uVyE6e5atTTQE",
    "data": [
      {
        "id": "sub_3uVyZtqbGP43Gy",
        "object": "line_item",
        "type": "subscription",
        "livemode": false,
        "amount": 0,
        "currency": "usd",
        "proration": false,
        "period": {
          "start": 1398323228,
          "end": 1398755228
        },
        "quantity": 1,
        "plan": {
          "interval": "month",
          "name": "PricingPlan 69",
          "created": 1398323226,
          "amount": 69,
          "currency": "usd",
          "id": "TestMode4",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": 5,
          "metadata": {
          },
          "statement_description": null
        },
        "description": null,
        "metadata": null
      }
    ]
  },
  "subtotal": 0,
  "total": 0,
  "customer": "cus_3uVyE6e5atTTQE",
  "object": "invoice",
  "attempted": true,
  "closed": true,
  "paid": true,
  "livemode": false,
  "attempt_count": 0,
  "amount_due": 0,
  "currency": "usd",
  "starting_balance": 0,
  "ending_balance": null,
  "next_payment_attempt": null,
  "charge": null,
  "discount": null,
  "application_fee": null,
  "subscription": "sub_3uVyZtqbGP43Gy",
  "metadata": {
  },
  "description": null
}

Invoice items

Sometimes you want to add a charge or credit to a customer but only actually charge the customer's card at the end of a regular billing cycle. This is useful for combining several charges to minimize per-transaction fees or having Stripe tabulate your usage-based billing totals.

The invoiceitem object

Attributes

id: string
object: string, value is "invoiceitem"
livemode: boolean
amount: integer
currency: currency
customer: string
date: timestamp
proration: boolean Whether or not the invoice item was created automatically as a proration adjustment when the customer switched plans
description: string
invoice: string
metadata: metadata hash A set of key/value pairs that you can attach to an invoice item object. It can be useful for storing additional information about the invoice item in a structured format.
subscription: string The subscription that this invoice item has been created for, if any.

{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}#<Stripe::InvoiceItem id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}<InvoiceItem invoiceitem  id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}com.stripe.model.InvoiceItem JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}

Creating an Invoice Item

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

Arguments

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

Returns

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

POST https://api.stripe.com/v1/invoiceitemsStripe::InvoiceItem.create()
stripe.InvoiceItem.create()
Stripe_InvoiceItem::create();
InvoiceItem.create();
stripe.invoiceItems.create();

curl https://api.stripe.com/v1/invoiceitems \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d customer=cus_3uVyE6e5atTTQE \
   -d amount=1000 \
   -d currency=usd \
   -d "description=One-time setup fee"require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::InvoiceItem.create(
    :customer => "cus_3uVyE6e5atTTQE",
    :amount => 1000,
    :currency => "usd",
    :description => "One-time setup fee"
)import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.InvoiceItem.create(
    customer="cus_3uVyE6e5atTTQE",
    amount=1000,
    currency="usd",
    description="One-time setup fee")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_InvoiceItem::create(array(
    "customer" => "cus_3uVyE6e5atTTQE",
    "amount" => 1000,
    "currency" => "usd",
    "description" => "One-time setup fee")
);Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> invoiceItemParams = new HashMap<String, Object>();
invoiceItemParams.put("customer", "cus_3uVyE6e5atTTQE");
invoiceItemParams.put("amount", 1000);
invoiceItemParams.put("currency", "usd");
invoiceItemParams.put("description", "One-time setup fee");

InvoiceItem.create(invoiceItemParams);var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoiceItems.create({
  customer: "cus_3uVyE6e5atTTQE",
  amount: 1000,
  currency: "usd",
  description: "One-time setup fee"
}, function(err, invoiceItem) {
  // asynchronously called
});

{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}#<Stripe::InvoiceItem id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}<InvoiceItem invoiceitem  id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}com.stripe.model.InvoiceItem JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}

Retrieving an Invoice Item

Retrieves the invoice item with the given ID.

Arguments

id: required The ID of the desired invoice item.

Returns

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

GET https://api.stripe.com/v1/invoiceitems/{ID}Stripe::InvoiceItem.retrieve({ID})
stripe.InvoiceItem.retrieve({ID})
Stripe_InvoiceItem::retrieve({ID});
InvoiceItem.retrieve({ID});
stripe.invoiceItems.retrieve({ID});

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

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

stripe.InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_InvoiceItem::retrieve("ii_103n902eZvKYlo2CfQmZCSQD");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD");var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoiceItems.retrieve("ii_103n902eZvKYlo2CfQmZCSQD", function(err, invoiceItem) {
  // asynchronously called
});

{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}#<Stripe::InvoiceItem id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}<InvoiceItem invoiceitem  id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}com.stripe.model.InvoiceItem JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}

Updating an Invoice Item

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

Arguments

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

Returns

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

POST https://api.stripe.com/v1/invoiceitems/{INVOICEITEM_ID}ii = Stripe::InvoiceItem.retrieve({INVOICEITEM_ID})
ii.amount = {AMOUNT}
...
ii.save
ii = stripe.InvoiceItem.retrieve({INVOICEITEM_ID})
ii.amount = {AMOUNT}
...
ii.save()
$ii = Stripe_InvoiceItem::retrieve({INVOICEITEM_ID});
$ii->amount = {AMOUNT};
...
$ii->save();
InvoiceItem ii = InvoiceItem.retrieve({INVOICEITEM_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("amount", {AMOUNT});
...
ii.update(updateParams);stripe.invoiceItems.update({INVOICEITEM_ID}, { amount: {AMOUNT} })

curl https://api.stripe.com/v1/invoiceitems/ii_103n902eZvKYlo2CfQmZCSQD \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=1500 \
   -d "description=Customer for test@example.com"require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ii = Stripe::InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD")
ii.amount = 1500
ii.description = "Customer for test@example.com"
ii.saveimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ii = stripe.InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD")
ii.amount = 1500
ii.description = "Customer for test@example.com"
ii.save()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ii = Stripe_InvoiceItem::retrieve("ii_103n902eZvKYlo2CfQmZCSQD");
$ii->amount = 1500;
$ii->description = "Customer for test@example.com";
$ii->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

InvoiceItem ii = InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("amount", 1500);
updateParams.put("description", "Customer for test@example.com");
ii.update(updateParams);var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.invoiceItems.update(
  "ii_103n902eZvKYlo2CfQmZCSQD",
  {
    amount: 1500,
    description: "Customer for test@example.com"
  },
  function(err, invoiceItem) {
    // asynchronously called
  }
);

{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 1500,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Customer for test@example.com",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}#<Stripe::InvoiceItem id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 1500,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Customer for test@example.com",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}<InvoiceItem invoiceitem  id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 1500,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Customer for test@example.com",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 1500,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Customer for test@example.com",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}com.stripe.model.InvoiceItem JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 1500,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Customer for test@example.com",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}{
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 1500,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Customer for test@example.com",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}

Deleting an Invoice Item

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

Arguments

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

Returns

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

DELETE https://api.stripe.com/v1/invoiceitems/{INVOICEITEM_ID}ii = Stripe::InvoiceItem.retrieve({INVOICEITEM_ID})
ii.delete
ii = stripe.InvoiceItem.retrieve({INVOICEITEM_ID})
ii.delete()
$ii = Stripe_InvoiceItem::retrieve({INVOICEITEM_ID});
$ii->delete();
InvoiceItem ii = InvoiceItem.retrieve({INVOICEITEM_ID});
ii.delete();
stripe.invoiceItems.del({INVOICEITEM_ID});

curl https://api.stripe.com/v1/invoiceitems/ii_103n902eZvKYlo2CfQmZCSQD \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X DELETErequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ii = Stripe::InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD")
ii.deleteimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

ii = stripe.InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD")
ii.delete()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ii = Stripe_InvoiceItem::retrieve("ii_103n902eZvKYlo2CfQmZCSQD");
$ii->delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

InvoiceItem ii = InvoiceItem.retrieve("ii_103n902eZvKYlo2CfQmZCSQD");
ii.delete();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

{
  "deleted": true,
  "id": "ii_103n902eZvKYlo2CfQmZCSQD"
}#<Stripe::Object id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: {
  "deleted": true,
  "id": "ii_103n902eZvKYlo2CfQmZCSQD"
}<Object object  id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: {
  "deleted": true,
  "id": "ii_103n902eZvKYlo2CfQmZCSQD"
}{
  "deleted": true,
  "id": "ii_103n902eZvKYlo2CfQmZCSQD"
}com.stripe.model.Object JSON: {
  "deleted": true,
  "id": "ii_103n902eZvKYlo2CfQmZCSQD"
}{
  "deleted": true,
  "id": "ii_103n902eZvKYlo2CfQmZCSQD"
}

List all Invoice Items

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

Arguments

created

optional A filter on the list based on the object created field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:

gtgtgtgtgtgt: optional Return values where the created field is after this timestamp.
gtegtegtegtegtegte: optional Return values where the created field is after or equal to this timestamp.
ltltltltltlt: optional Return values where the created field is before this timestamp.
ltelteltelteltelte: optional Return values where the created field is before or equal to this timestamp.

customer

optional The identifier of the customer whose invoice items to return. If none is provided, all invoice items will be returned.

ending_before

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

limit

optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

starting_after

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

Returns

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

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

GET https://api.stripe.com/v1/invoiceitemsStripe::InvoiceItem.allstripe.InvoiceItem.all()Stripe_InvoiceItem->all();InvoiceItem.all(Map options);stripe.invoiceItems.list();

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

Stripe::InvoiceItem.allimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.InvoiceItem.all()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_InvoiceItem::all();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

InvoiceItem.all(new HashMap<String, Object>());var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

{
  "object": "list",
  "url": "/v1/invoiceitems",
  "has_more": false,
  "data": [
    {
    "object": "invoiceitem",
    "id": "ii_103n902eZvKYlo2CfQmZCSQD",
    "date": 1396623292,
    "amount": 0,
    "livemode": false,
    "proration": false,
    "currency": "usd",
    "customer": "cus_3uVyE6e5atTTQE",
    "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
    "metadata": {
    },
    "invoice": null,
    "subscription": null
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "/v1/invoiceitems",
  "data": [
    #<Stripe::InvoiceItem id=ii_103n902eZvKYlo2CfQmZCSQD 0x00000a> JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
},
    #<Stripe::InvoiceItem[...] ...>,
    #<Stripe::InvoiceItem[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/invoiceitems",
  has_more: false,
  data: [
    <InvoiceItem invoiceitem  id=ii_103n902eZvKYlo2CfQmZCSQD at 0x00000a> JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
},
    <stripe.InvoiceItem[...] ...>,
    <stripe.InvoiceItem[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "/v1/invoiceitems",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
}
    [1] => <Stripe_InvoiceItem[...] ...>
    [2] => <Stripe_InvoiceItem[...] ...>
  )
)
#<com.stripe.model.InvoiceItemCollection id=#> JSON: {
  "data": [
    com.stripe.model.InvoiceItem JSON: {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
},
    #<com.stripe.model.InvoiceItem[...] ...>,
    #<com.stripe.model.InvoiceItem[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/invoiceitems",
  "has_more": false,
  "data": [
    {
  "object": "invoiceitem",
  "id": "ii_103n902eZvKYlo2CfQmZCSQD",
  "date": 1396623292,
  "amount": 0,
  "livemode": false,
  "proration": false,
  "currency": "usd",
  "customer": "cus_3uVyE6e5atTTQE",
  "description": "Invoice item: 1a018775-a110-419b-9a4b-e42094561296",
  "metadata": {
  },
  "invoice": null,
  "subscription": null
},
    {...},
    {...}
  ]
}

Disputes

A dispute occurs when a customer questions your charge with their bank or credit card company. When a customer disputes your charge, you're given the opportunity to respond to the dispute with evidence that shows the charge is legitimate. You can find more information about the dispute process in our disputes FAQ.

The dispute object

Attributes

object: string, value is "dispute"
livemode: boolean
amount: integer Disputed amount. Usually the amount of the charge, but can differ (usually because of currency fluctuation or because only part of the order is disputed).
charge: string ID of the charge that was disputed
created: timestamp Date dispute was opened
currency: currency Three-letter ISO currency code representing the currency in which the disputed charge was made.
reason: string Reason given by cardholder for dispute. Possible values are duplicate, fraudulent, subscription_canceled, product_unacceptable, product_not_received, unrecognized, credit_not_processed, general. Read more about dispute reasons.
status: string Current status of dispute. Possible values are won, lost, needs_response, under_review.
balance_transaction: string Balance transaction that describes the impact of this dispute on your account balance.
evidence: string Evidence that you have submitted to demonstrate the charge is legitimate (proof of delivery, IP addresses of logins, text of invoices, etc.). There is a limit of 300,000 characters.
evidence_due_by: timestamp Date by which evidence must be submitted in order to successfully challenge dispute. Will be null if the customer’s bank or credit card company doesn’t allow a response for this particular dispute.
is_protected: boolean

{
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}#<Stripe::Dispute 0x00000a> JSON: {
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}<Dispute dispute  at 0x00000a> JSON: {
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}{
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}com.stripe.model.Dispute JSON: {
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}{
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}

Updating a dispute

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

Arguments

evidence: optional

Returns

Returns the dispute object.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/disputecharge = Stripe::Charge.retrieve({CHARGE_ID})
charge.update_dispute(:evidence => {NEW_EVIDENCE})
charge = stripe.Charge.retrieve({CHARGE_ID})
charge.update_dispute(evidence={NEW_EVIDENCE})
$charge = Stripe_Charge::retrieve({CHARGE_ID});
$charge.updateDispute(array("evidence" => {NEW_EVIDENCE}));
Charge ch = Charge.retrieve({CHARGE_ID});
Map disputeParams = new HashMap();
disputeParams.put("evidence", {NEW_EVIDENCE});
ch.updateDispute(disputeParams);
stripe.charges.updateDispute({CHARGE_ID}, {
  evidence: {NEW_EVIDENCE}
});

curl https://api.stripe.com/v1/charges/ch_103uVx2eZvKYlo2CO1scPlyg/dispute \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d "evidence=Here's evidence showing this charge is legitimate."require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = Stripe::Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")
charge.update_dispute(:evidence => "Here's evidence showing this charge is legitimate.")import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = stripe.Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")
charge.update_dispute(evidence="Here's evidence showing this charge is legitimate.")
charge.save()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = Stripe_Charge::retrieve("ch_103uVx2eZvKYlo2CO1scPlyg");
$ch->updateDispute(array("evidence" => "Here's evidence showing this charge is legitimate."));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge ch = Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg");
Map<String, Object> params = new HashMap<String, Object>();
params.put("evidence", "Here's evidence showing this charge is legitimate.");
ch.updateDispute(params)var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.charges.updateDispute(
  "ch_103uVx2eZvKYlo2CO1scPlyg",
  {evidence: "Here's evidence showing this charge is legitimate."},
  function(err, dispute) {
    // asynchronously called
  }
);

{
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": "Here's evidence showing this charge is legitimate."
}#<Stripe::Dispute 0x00000a> JSON: {
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": "Here's evidence showing this charge is legitimate."
}<Dispute dispute  at 0x00000a> JSON: {
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": "Here's evidence showing this charge is legitimate."
}{
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": "Here's evidence showing this charge is legitimate."
}com.stripe.model.Dispute JSON: {
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": "Here's evidence showing this charge is legitimate."
}{
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "needs_response",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": "Here's evidence showing this charge is legitimate."
}

Closing a dispute

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

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

Arguments

id: required

Returns

Returns the dispute object.

POST https://api.stripe.com/v1/charges/{CHARGE_ID}/dispute/closecharge = Stripe::Charge.retrieve({CHARGE_ID})
charge.close_dispute
charge = stripe.Charge.retrieve({CHARGE_ID})
charge.close_dispute()
$charge = Stripe_Charge::retrieve({CHARGE_ID});
$charge.closeDispute();
Charge ch = Charge.retrieve({CHARGE_ID});
ch.closeDispute();
stripe.charges.closeDispute({CHARGE_ID});

curl https://api.stripe.com/v1/charges/ch_103uVx2eZvKYlo2CO1scPlyg/dispute/close \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POSTrequire "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = Stripe::Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")
charge.close_disputeimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

charge = stripe.Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg")
charge.close_dispute()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$ch = Stripe_Charge::retrieve("ch_103uVx2eZvKYlo2CO1scPlyg");
$ch->closeDispute();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Charge ch = Charge.retrieve("ch_103uVx2eZvKYlo2CO1scPlyg");
ch.closeDispute()var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

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

{
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "lost",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}#<Stripe::Dispute 0x00000a> JSON: {
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "lost",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}<Dispute dispute  at 0x00000a> JSON: {
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "lost",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}{
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "lost",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}com.stripe.model.Dispute JSON: {
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "lost",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}{
  "charge": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "amount": 1000,
  "created": 1398323301,
  "status": "lost",
  "livemode": false,
  "currency": "usd",
  "object": "dispute",
  "reason": "general",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "evidence_due_by": 1400025599,
  "evidence": null
}

Transfers

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

Currently, only US accounts can create transfers.

View the documentation on creating transfers via the API.

The transfer object

Attributes

id

string

object

string, value is "transfer"

livemode

boolean

amount

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

created

timestamp Time that this record of the transfer was first created.

currency

currency

date

timestamp Date the transfer was initiated. If the transfer is pending, the date the transfer is scheduled to go out.

status

string Current status of the transfer (paid, pending, or failed). A transfer will be pending until it is submitted, at which point it becomes paid. If it does not go through successfully, its status will change to failed.

account

hash or null Hash describing the account this transfer was sent to

id: string
object: string
bank_name: string Name of the bank associated with the routing number, e.g. WELLS FARGO.
country: string Two-letter ISO code representing the country the bank account is located in.
currency: currency Three-letter ISO currency code representing the currency paid out to the bank account.
last4: string
disabled: boolean or null When a transfer sent to this bank account fails, we’ll set the disabled property to true and will not continue to send transfers until the bank details are updated.
fingerprint: string or null Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.
validated: boolean or null Whether or not the bank account exists. If false, there isn’t enough information to know (e.g. for smaller credit unions), or the validation is not being run.

balance_transaction

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

description

string Internal-only description of the transfer

metadata

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

recipient

string ID of the recipient this transfer is for if one exists. Transfers to your bank account do not have a recipient.

statement_description

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

{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}#<Stripe::Transfer id=tr_103uRF2eZvKYlo2CjSwpQUBm 0x00000a> JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}<Transfer transfer  id=tr_103uRF2eZvKYlo2CjSwpQUBm at 0x00000a> JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}com.stripe.model.Transfer JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}

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

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

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

Arguments

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

Returns

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

POST https://api.stripe.com/v1/transfersStripe::Transfer.createstripe.Transfer.create()Stripe_Transfer::create();Transfer.create();stripe.transfers.create();

curl https://api.stripe.com/v1/transfers \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d amount=400 \
   -d currency=usd \
   -d recipient=rp_103tz12eZvKYlo2CUs7xNCbd \
   -d "description=Transfer to test@example.com"require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

stripe.Transfer.create(
  amount=400,
  currency="usd",
  recipient="rp_103tz12eZvKYlo2CUs7xNCbd",
  description="Transfer for test@example.com"
)require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Transfer::create(array(
  "amount" => 400,
  "currency" => "usd",
  "recipient" => "rp_103tz12eZvKYlo2CUs7xNCbd",
  "description" => "Transfer for test@example.com"
));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> transferParams = new HashMap<String, Object>();
transferParams.put("amount", 400);
transferParams.put("currency", "usd");
transferParams.put("recipient", "rp_103tz12eZvKYlo2CUs7xNCbd");
transferParams.put("description", "Transfer for test@example.com");

Transfer.create(transferParams);var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.transfers.create({
  amount: 400,
  currency: "usd",
  recipient: "rp_103tz12eZvKYlo2CUs7xNCbd",
  description: "Transfer for test@example.com"
}, function(err, transfer) {
  // asynchronously called
});

{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}#<Stripe::Transfer id=tr_103uRF2eZvKYlo2CjSwpQUBm 0x00000a> JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}<Transfer transfer  id=tr_103uRF2eZvKYlo2CjSwpQUBm at 0x00000a> JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}com.stripe.model.Transfer JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}

Retrieving a Transfer

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

Arguments

id: required The identifier of the transfer to be retrieved.

Returns

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

GET https://api.stripe.com/v1/transfers/{TRANSFER_ID}Stripe::Transfer.retrieve({TRANSFER_ID})stripe.Transfer.retrieve({TRANSFER_ID})Stripe_Transfer::retrieve({TRANSFER_ID});Transfer.retrieve({TRANSFER_ID});stripe.transfers.retrieve({TRANSFER_ID});

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

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

stripe.Transfer.retrieve("tr_103uRF2eZvKYlo2CjSwpQUBm")require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Transfer::retrieve("tr_103uRF2eZvKYlo2CjSwpQUBm");Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

stripe.transfers.retrieve("tr_103uRF2eZvKYlo2CjSwpQUBm", function(err, transfer) {
  // asynchronously called
});

{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}#<Stripe::Transfer id=tr_103uRF2eZvKYlo2CjSwpQUBm 0x00000a> JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}<Transfer transfer  id=tr_103uRF2eZvKYlo2CjSwpQUBm at 0x00000a> JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}com.stripe.model.Transfer JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}

Updating a Transfer

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

This request accepts only the description and metadata as arguments.

Arguments

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

Returns

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

POST https://api.stripe.com/v1/transfers/{TRANSFER_ID}tr = Stripe::Transfer.retrieve({CUSTOMER_ID})
tr.description = {NEW_DESCRIPTION}
...
tr.save
tr = stripe.Transfer.retrieve({CUSTOMER_ID})
tr.description = {NEW_DESCRIPTION}
...
tr.save()
$tr = Stripe_Transfer::retrieve({CUSTOMER_ID});
$tr->description = {NEW_DESCRIPTION};
...
$tr->save();
Transfer tr = Transfer.retrieve({CUSTOMER_ID});
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", {NEW_DESCRIPTION});
...
tr.update(updateParams);stripe.transfers.update({CHARGE_ID}, {
  description: {NEW_DESCRIPTION}
});

curl https://api.stripe.com/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d "description=Transfer for test@example.com"require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

tr = Stripe::Transfer.retrieve("tr_103uRF2eZvKYlo2CjSwpQUBm")
tr.description = "Transfer for test@example.com"
tr.saveimport stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

tr = stripe.Transfer.retrieve("tr_103uRF2eZvKYlo2CjSwpQUBm")
tr.description = "Transfer for test@example.com"
tr.save()require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$tr = Stripe_Transfer::retrieve("tr_103uRF2eZvKYlo2CjSwpQUBm");
$tr->description = "Transfer for test@example.com";
$tr->save();Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Transfer tr = Transfer.retrieve("tr_103uRF2eZvKYlo2CjSwpQUBm");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", "Transfer for test@example.com");

tr.update(updateParams);var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.transfers.update(
  "ch_103uVx2eZvKYlo2CO1scPlyg",
  {
    description: "Transfer for test@example.com"
  },
  function(err, transfer) {
    // asynchronously called
  }
);

{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "Transfer to test@example.com",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}#<Stripe::Transfer id=tr_103uRF2eZvKYlo2CjSwpQUBm 0x00000a> JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "Transfer to test@example.com",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}<Transfer transfer  id=tr_103uRF2eZvKYlo2CjSwpQUBm at 0x00000a> JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "Transfer to test@example.com",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "Transfer to test@example.com",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}com.stripe.model.Transfer JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "Transfer to test@example.com",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "Charge for test@example.com",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}

Canceling a Transfer

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

Arguments

id: required The identifier of the transfer to be canceled.

Returns

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

POST https://api.stripe.com/v1/transfers/{TRANSFER_ID}/cancelNo Ruby bindings available.No Python bindings available.No PHP bindings available.No Java bindings available.stripe.transfers.cancel({TRANSFER_ID});

curl https://api.stripe.com/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/cancel \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -X POSTNo Ruby bindings available.No Python bindings available.No PHP bindings available.No Java bindings available.var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.transfers.cancel("ch_103uVx2eZvKYlo2CO1scPlyg", function(err, transfer) {
  // asynchronously called
});

{
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "canceled",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}No Ruby bindings available.No Python bindings available.No PHP bindings available.No Java bindings available.{
  "id": "ch_103uVx2eZvKYlo2CO1scPlyg",
  "object": "charge",
  "created": 1398323170,
  "livemode": false,
  "paid": true,
  "amount": 500,
  "currency": "usd",
  "refunded": "true",
  "card": {
    "id": "card_103uVx2eZvKYlo2C4xDNcx3t",
    "object": "card",
    "last4": "4242",
    "type": "Visa",
    "exp_month": 1,
    "exp_year": 2050,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "customer": null,
    "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
  },
  "captured": true,
  "refunds": [
    {
      "amount": 500,
      "currency": "usd",
      "created": 1398323301,
      "object": "refund",
      "balance_transaction": "txn_3uW03bX4vEgHqP"
    }
  ],
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "failure_message": null,
  "failure_code": null,
  "amount_refunded": 500,
  "customer": null,
  "invoice": null,
  "description": null,
  "dispute": null,
  "metadata": {
  },
  "statement_description": null
}

List all Transfers

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

Arguments

created

optional A filter on the list based on the object created field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:

gtgtgtgtgtgt: optional Return values where the created field is after this timestamp.
gtegtegtegtegtegte: optional Return values where the created field is after or equal to this timestamp.
ltltltltltlt: optional Return values where the created field is before this timestamp.
ltelteltelteltelte: optional Return values where the created field is before or equal to this timestamp.

date

optional A filter on the list based on the object date field. The value can be a string with an exact UTC timestamp, or it can be a dictionaryhashdictionaryassociative arrayMapobject with the following options:

gtgtgtgtgtgt: optional Return values where the date field is after this timestamp.
gtegtegtegtegtegte: optional Return values where the date field is after or equal to this timestamp.
ltltltltltlt: optional Return values where the date field is before this timestamp.
ltelteltelteltelte: optional Return values where the date field is before or equal to this timestamp.

ending_before

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

limit

optional — default is 10 A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

recipient

optional Only return transfers for the recipient specified by this recipient ID.

starting_after

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

status

optional Only return transfers that have the given status: pending, paid, or failed.

Returns

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

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

GET https://api.stripe.com/v1/transfersStripe::Transfer.allstripe.Transfer.all()Stripe_Transfer::all();Transfer.all(Map options);stripe.transfers.list();

curl https://api.stripe.com/v1/transfers?count=3 \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:require "stripe"
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Transfer.all(:count => 3)import stripe
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Transfer.all(count=3)require_once('./lib/Stripe.php');
Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

Stripe_Transfer::all(array("count" => 3));Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

Transfer.all(transferParams);var stripe = require("stripe")(
  "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

stripe.transfers.list({ count: 3 }, function(err, transfers) {
  // asynchronously called
});

{
  "object": "list",
  "url": "/v1/transfers",
  "has_more": false,
  "data": [
    {
    "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
    "object": "transfer",
    "created": 1398305608,
    "date": 1398470400,
    "livemode": false,
    "amount": 499988,
    "currency": "usd",
    "status": "pending",
    "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
    "summary": {
      "charge_gross": 526986,
      "charge_fees": 26998,
      "charge_fee_details": [
        {
          "amount": 26998,
          "currency": "usd",
          "type": "stripe_fee",
          "description": null,
          "application": null
        }
      ],
      "refund_gross": 0,
      "refund_fees": 0,
      "refund_fee_details": [
  
      ],
      "adjustment_gross": 0,
      "adjustment_fees": 0,
      "adjustment_fee_details": [
  
      ],
      "validation_fees": 0,
      "validation_count": 0,
      "charge_count": 386,
      "refund_count": 0,
      "adjustment_count": 0,
      "net": 499988,
      "currency": "usd",
      "collected_fee_gross": 0,
      "collected_fee_count": 0,
      "collected_fee_refund_gross": 0,
      "collected_fee_refund_count": 0
    },
    "transactions": {
      "object": "list",
      "total_count": 386,
      "has_more": true,
      "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
      "data": [
        {
          "id": "ch_103su82eZvKYlo2Cj6PThF5o",
          "type": "charge",
          "amount": 500,
          "currency": "usd",
          "net": 455,
          "created": 1397951784,
          "description": null,
          "fee": 45,
          "fee_details": [
            {
              "amount": 45,
              "currency": "usd",
              "type": "stripe_fee",
              "description": "Stripe processing fees",
              "application": null
            }
          ]
        },
        {
          "id": "ch_103su32eZvKYlo2C7mrvcU4b",
          "type": "charge",
          "amount": 500,
          "currency": "usd",
          "net": 455,
          "created": 1397951483,
          "description": null,
          "fee": 45,
          "fee_details": [
            {
              "amount": 45,
              "currency": "usd",
              "type": "stripe_fee",
              "description": "Stripe processing fees",
              "application": null
            }
          ]
        },
        {
          "id": "ch_103su12eZvKYlo2CaG51GD0Q",
          "type": "charge",
          "amount": 400,
          "currency": "usd",
          "net": 358,
          "created": 1397951402,
          "description": "Charge for test@example.com",
          "fee": 42,
          "fee_details": [
            {
              "amount": 42,
              "currency": "usd",
              "type": "stripe_fee",
              "description": "Stripe processing fees",
              "application": null
            }
          ]
        },
        {
          "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
          "type": "charge",
          "amount": 500,
          "currency": "usd",
          "net": 455,
          "created": 1397951195,
          "description": null,
          "fee": 45,
          "fee_details": [
            {
              "amount": 45,
              "currency": "usd",
              "type": "stripe_fee",
              "description": "Stripe processing fees",
              "application": null
            }
          ]
        },
        {
          "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
          "type": "charge",
          "amount": 500,
          "currency": "usd",
          "net": 455,
          "created": 1397950904,
          "description": null,
          "fee": 45,
          "fee_details": [
            {
              "amount": 45,
              "currency": "usd",
              "type": "stripe_fee",
              "description": "Stripe processing fees",
              "application": null
            }
          ]
        }
      ]
    },
    "other_transfers": [
      "tr_103uRF2eZvKYlo2CjSwpQUBm"
    ],
    "account": null,
    "description": "STRIPE TRANSFER",
    "metadata": {
    },
    "statement_description": null,
    "recipient": null
  },
    {...},
    {...}
  ]
}
#<Stripe::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "count": 3,
  "url": "/v1/transfers",
  "data": [
    #<Stripe::Transfer id=tr_103uRF2eZvKYlo2CjSwpQUBm 0x00000a> JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
},
    #<Stripe::transfer[...] ...>,
    #<Stripe::transfer[...] ...>
  ]
}

{
  object: "list",
  url: "/v1/transfers",
  has_more: false,
  data: [
    <Transfer transfer  id=tr_103uRF2eZvKYlo2CjSwpQUBm at 0x00000a> JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
},
    <stripe.transfer[...] ...>,
    <stripe.transfer[...] ...>
  ]
}
Array(
  "object" => "list",
  "url" => "/v1/transfers",
  "has_more" => false,
  "data" => Array(
    [0] => {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
}
    [1] => <Stripe_transfer[...] ...>
    [2] => <Stripe_transfer[...] ...>
  )
)
#<com.stripe.model.transferCollection id=#> JSON: {
  "data": [
    com.stripe.model.Transfer JSON: {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
},
    #<com.stripe.model.transfer[...] ...>,
    #<com.stripe.model.transfer[...] ...>
  ],
  "has_more": false
}
{
  "object": "list",
  "url": "/v1/transfers",
  "has_more": false,
  "data": [
    {
  "id": "tr_103uRF2eZvKYlo2CjSwpQUBm",
  "object": "transfer",
  "created": 1398305608,
  "date": 1398470400,
  "livemode": false,
  "amount": 499988,
  "currency": "usd",
  "status": "pending",
  "balance_transaction": "txn_103sA82eZvKYlo2C42IqwOhZ",
  "summary": {
    "charge_gross": 526986,
    "charge_fees": 26998,
    "charge_fee_details": [
      {
        "amount": 26998,
        "currency": "usd",
        "type": "stripe_fee",
        "description": null,
        "application": null
      }
    ],
    "refund_gross": 0,
    "refund_fees": 0,
    "refund_fee_details": [

    ],
    "adjustment_gross": 0,
    "adjustment_fees": 0,
    "adjustment_fee_details": [

    ],
    "validation_fees": 0,
    "validation_count": 0,
    "charge_count": 386,
    "refund_count": 0,
    "adjustment_count": 0,
    "net": 499988,
    "currency": "usd",
    "collected_fee_gross": 0,
    "collected_fee_count": 0,
    "collected_fee_refund_gross": 0,
    "collected_fee_refund_count": 0
  },
  "transactions": {
    "object": "list",
    "total_count": 386,
    "has_more": true,
    "url": "/v1/transfers/tr_103uRF2eZvKYlo2CjSwpQUBm/transactions",
    "data": [
      {
        "id": "ch_103su82eZvKYlo2Cj6PThF5o",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951784,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su32eZvKYlo2C7mrvcU4b",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951483,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103su12eZvKYlo2CaG51GD0Q",
        "type": "charge",
        "amount": 400,
        "currency": "usd",
        "net": 358,
        "created": 1397951402,
        "description": "Charge for test@example.com",
        "fee": 42,
        "fee_details": [
          {
            "amount": 42,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103sty2eZvKYlo2CFQolk6Ro",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397951195,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      },
      {
        "id": "ch_103stt2eZvKYlo2Cnk47Y9pl",
        "type": "charge",
        "amount": 500,
        "currency": "usd",
        "net": 455,
        "created": 1397950904,
        "description": null,
        "fee": 45,
        "fee_details": [
          {
            "amount": 45,
            "currency": "usd",
            "type": "stripe_fee",
            "description": "Stripe processing fees",
            "application": null
          }
        ]
      }
    ]
  },
  "other_transfers": [
    "tr_103uRF2eZvKYlo2CjSwpQUBm"
  ],
  "account": null,
  "description": "STRIPE TRANSFER",
  "metadata": {
  },
  "statement_description": null,
  "recipient": null
},
    {...},
    {...}
  ]
}

Recipients

With recipient objects, you can transfer money from your Stripe account to a third party bank account. The API allows you to create, delete, and update your recipients. You can retrieve individual recipients as well as a list of all your recipients.

The recipient object

Attributes

id

string

object

string, value is "recipient"

livemode

boolean

created

timestamp

type

string Type of the recipient, one of individual or corporation.

active_account

hash or null Hash describing the current account on the recipient, if there is one.

id: string
object: string
bank_name: string Name of the bank associated with the routing number, e.g. WELLS FARGO.
country: string Two-letter ISO code representing the country the bank account is located in.
currency: currency Three-letter ISO currency code representing the currency paid out to the bank account.
last4: string
disabled: boolean or null When a transfer sent to this bank account fails, we’ll set the disabled property to true and will not continue to send transfers until the bank details are updated.
fingerprint: string or null Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.
validated: boolean or null Whether or not the bank account exists. If false, there isn’t enough information to know (e.g. for smaller credit unions), or the validation is not being run.

description

string

email

string

metadata

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

name

string Full, legal name of the recipient.

{
  "id": "rp_103tz12eZvKYlo2CUs7xNCbd",
  "object": "recipient",
  "created": 1398200622,
  "livemode": false,
  "type": "individual",
  "description": null,
  "email": null,
  "name": "John Doe",
  "verified": false,
  "metadata": {
  },
  "active_account": null
}#<Stripe::Recipient id=rp_103tz12eZvKYlo2CUs7xNCbd 0x00000a> JSON: {
  "id": "rp_103tz12eZvKYlo2CUs7xNCbd",
  "object": "recipient",
  "created": 1398200622,
  "livemode": false,
  "type": "individual",
  "description": null,
  "email": null,
  "name": "John Doe",
  "verified": false,
  "metadata": {
  },
  "active_account": null
}<Recipient recipient  id=rp_103tz12eZvKYlo2CUs7xNCbd at 0x00000a> JSON: {
  "id": "rp_103tz12eZvKYlo2CUs7xNCbd",
  "object": "recipient",
  "created": 1398200622,
  "livemode": false,
  "type": "individual",
  "description": null,
  "email": null,
  "name": "John Doe",
  "verified": false,
  "metadata": {
  },
  "active_account": null
}{
  "id": "rp_103tz12eZvKYlo2CUs7xNCbd",
  "object": "recipient",
  "created": 1398200622,
  "livemode": false,
  "type": "individual",
  "description": null,
  "email": null,
  "name": "John Doe",
  "verified": false,
  "metadata": {
  },
  "active_account": null
}com.stripe.model.Recipient JSON: {
  "id": "rp_103tz12eZvKYlo2CUs7xNCbd",
  "object": "recipient",
  "created": 1398200622,
  "livemode": false,
  "type": "individual",
  "description": null,
  "email": null,
  "name": "John Doe",
  "verified": false,
  "metadata": {
  },
  "active_account": null
}{
  "id": "rp_103tz12eZvKYlo2CUs7xNCbd",
  "object": "recipient",
  "created": 1398200622,
  "livemode": false,
  "type": "individual",
  "description": null,
  "email": null,
  "name": "John Doe",
  "verified": false,
  "metadata": {
  },
  "active_account": null
}

Creating a New Recipient

Creates a new recipient object and verifies both the recipient identity and bank account information.

Arguments

name

required The recipient's full, legal name. For type individual, should be in the format "First Last", "First Middle Last", or "First M Last" (no prefixes or suffixes). For corporation, the full incorporated name.

type

required Type of the recipient: either individual or corporation.

tax_id

optional The recipient's tax ID, as a string. For type individual, the full SSN; for type corporation, the full EIN.

bank_account

optional, default is nullnilNonenullnullnull A bank account to attach to the recipient.

countrycountrycountrycountrycountrycountry: required The country the bank account is in. Currently, only US is supported.
routing_numberrouting_numberrouting_numberrouting_numberrouting_numberrouting_number: required The routing number for the bank account in string form. This should be the ACH routing number, not the wire routing number.
account_numberaccount_numberaccount_numberaccount_numberaccount_numberaccount_number: required The account number for the bank account in string form. Must be a checking account.

email

optional, default is nullnilNonenullnullnull The recipient's email address. It is displayed alongside the recipient in the web interface and can be useful for searching and tracking.

description

optional, default is nullnilNonenullnullnull An arbitrary string which you can attach to a recipient object. It is displayed alongside the recipient in the web interface.

metadata

optional, default is { }{ }{ }{ }{ }{ } A set of key/value pairs that you can a

Stripe

API Reference

Libraries

API Endpoint

Summary of Resource URL Patterns

Authentication

Errors

Attributes

HTTP Status Code Summary

Errors

Types

Codes

Handling errors

Pagination

Pagination Arguments

List Response Format

Versioning

Expanding Objects

Metadata

Sample metadata use cases

Charges

The charge object

Attributes

Creating a new charge (charging a credit card)

Arguments

Returns

Verification Reponses

CVC Verification - card[cvc_check]

Address Line - card[address_line1_check]

Address ZIP - card[address_zip_check]

Retrieving a Charge

Arguments

Returns

Updating a Charge

Arguments

Returns

Refunding a Charge

Arguments

Returns

Capture a charge

Arguments

Returns

List all Charges

Arguments

Returns

Customers

The customer object

Attributes

Creating a New Customer

Arguments

Returns

Retrieving a Customer

Arguments

Returns

Updating a Customer

Arguments

Returns

Deleting a Customer

Arguments

Returns

List all Customers

Arguments

Returns

Cards

The card object

Attributes

Creating a new card

Arguments

Returns

Retrieving a customer's card

Arguments

Returns

Updating a card

Arguments

Returns

Deleting cards

Arguments

Returns

Listing cards

Arguments

CVC Verification - `card[cvc_check]`

Address Line - `card[address_line1_check]`

Address ZIP - `card[address_zip_check]`