· 9 years ago · Oct 06, 2016, 04:16 PM
1# Stripe Package
2This blocks allows you to translates a sting of text from one language to another
3* Domain: stripe.com
4* Credentials: secretKey, pubKey
5
6## How to get credentials:
70. Item one
81. Item two
9
10## TOC:
11* [getAccountBalance](#getAccountBalance)
12* [getBalanceHistory](#getBalanceHistory)
13* [createCharge](#createCharge)
14* [createCustomer](#createCustomer)
15* [getBalanceTransaction](#getBalanceTransaction)
16* [getCharge](#getCharge)
17* [updateCharge](#updateCharge)
18* [captureCharge](#captureCharge)
19* [getChargesList](#getChargesList)
20* [getCustomer](#getCustomer)
21* [updateCustomer](#updateCustomer)
22* [getBalanceTransaction](#getBalanceTransaction)
23* [deleteCustomer](#deleteCustomer)
24* [getCustomerList](#getCustomerList)
25* [getDispute](#getDispute)
26* [updateDispute](#updateDispute)
27* [closeDispute](#closeDispute)
28* [getDisputes](#getDisputes)
29* [getEvent](#getEvent)
30* [getEventList](#getEventList)
31* [createFileUpload](#createFileUpload)
32* [createRefund](#createRefund)
33* [getRefund](#getRefund)
34* [updateRefund](#updateRefund)
35* [getRefundList](#getRefundList)
36* [createCardToken](#createCardToken)
37* [createBankAccountToken](#createBankAccountToken)
38* [createPiiToken](#createPiiToken)
39* [getToken](#getToken)
40* [createTransfer](#createTransfer)
41* [getTransfer](#getTransfer)
42* [updateTransfer](#updateTransfer)
43* [getTransferList](#getTransferList)
44* [createTransferReversal](#createTransferReversal)
45* [getTransferReversal](#getTransferReversal)
46* [updateTransferReversal](#updateTransferReversal)
47* [getTransferReversalList](#getTransferReversalList)
48* [createAccount](#createAccount)
49* [getAccount](#getAccount)
50* [updateAccount](#updateAccount)
51* [deleteAccount](#deleteAccount)
52* [rejectAccount](#rejectAccount)
53* [getAccountList](#getAccountList)
54* [createFeeRefund](#createFeeRefund)
55* [getFeeRefund](#getFeeRefund)
56* [updateFeeRefund](#updateFeeRefund)
57* [getFeeRefundList](#getFeeRefundList)
58* [getApplicationFee](#getApplicationFee)
59* [getApplicationFeeList](#getApplicationFeeList)
60* [getCountrySpecsList](#getCountrySpecsList)
61* [getCountrySpec](#getCountrySpec)
62* [createBankAccount](#createBankAccount)
63* [getBankAccount](#getBankAccount)
64* [updateBankAccount](#updateBankAccount)
65* [deleteBankAccount](#deleteBankAccount)
66* [getBankAccountList](#getBankAccountList)
67* [createCard](#createCard)
68* [getCard](#getCard)
69* [updateCard](#updateCard)
70* [deleteCard](#deleteCard)
71* [getCardList](#getCardList)
72* [createReceiver](#createReceiver)
73* [getReceiver](#getReceiver)
74* [getReceiverList](#getReceiverList)
75* [createOrder](#createOrder)
76* [getOrder](#getOrder)
77* [updateOrder](#updateOrder)
78* [payOrder](#payOrder)
79* [getOrderList](#getOrderList)
80* [returnOrder](#returnOrder)
81* [getOrderReturn](#getOrderReturn)
82* [getOrderReturnList](#getOrderReturnList)
83* [createProduct](#createProduct)
84* [getProduct](#getProduct)
85* [updateProduct](#updateProduct)
86* [getProductList](#getProductList)
87* [deleteProduct](#deleteProduct)
88* [createSKU](#createSKU)
89* [getSKU](#getSKU)
90* [updateSKU](#updateSKU)
91* [getSKUList](#getSKUList)
92* [deleteSKU](#deleteSKU)
93* [createCoupon](#createCoupon)
94* [getCoupon](#getCoupon)
95* [updateCoupon](#updateCoupon)
96* [deleteCoupon](#deleteCoupon)
97* [getCouponList](#getCouponList)
98* [deleteCustomerDiscount](#deleteCustomerDiscount)
99* [deleteSubscriptionDiscount](#deleteSubscriptionDiscount)
100* [createInvoice](#createInvoice)
101* [getInvoice](#getInvoice)
102* [getInvoiceLineItems](#getInvoiceLineItems)
103* [updateInvoice](#updateInvoice)
104* [payInvoice](#payInvoice)
105* [getInvoiceList](#getInvoiceList)
106* [getInvoiceList](#getInvoiceList)
107* [createInvoiceItem](#createInvoiceItem)
108* [getInvoiceItem](#getInvoiceItem)
109* [updateInvoiceItem](#updateInvoiceItem)
110* [deleteInvoiceItem](#deleteInvoiceItem)
111* [getInvoiceItemsList](#getInvoiceItemsList)
112* [createPlan](#createPlan)
113* [getPlan](#getPlan)
114* [updatePlan](#updatePlan)
115* [deletePlan](#deletePlan)
116* [getPlanList](#getPlanList)
117* [createSubscription](#createSubscription)
118* [getSubscription](#getSubscription)
119* [updateSubscription](#updateSubscription)
120* [cancelSubscription](#cancelSubscription)
121* [getSubscriptionList](#getSubscriptionList)
122
123<a name="getAccountBalance"/>
124## Stripe.getAccountBalance
125Method description
126
127| Field | Type | Description
128|-------|------------|----------
129| apiKey| credentials| The api key obtained from Stripe.
130
131#### Request example
132```json
133{ "apiKey": "..."
134}
135```
136#### Response example
137```json
138{
139 "callback":"success",
140 "contextWrites":{
141 "#":{
142 "to":"..."
143 }
144 }
145}
146```
147
148<a name="getBalanceHistory"/>
149## Stripe.getBalanceHistory
150Method description
151
152| Field | Type | Description
153|--------------|------------|----------
154| apiKey | credentials| The api key obtained from Stripe.
155| currency | String | 3-letter ISO code for currency.
156| startingAfter| String | 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.
157| limit | Number | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
158| type | String | Only returns transactions of the given type. One of: `charge`, `refund`, `adjustment`, `application_fee`, `application_fee_refund`, `transfer`, or `transfer_failure`
159
160#### Request example
161```json
162{ "apiKey": "...",
163 "currency": "...",
164 "startingAfter": "...",
165 "limit": 0,
166 "type": "..."
167}
168```
169#### Response example
170```json
171{
172 "callback":"success",
173 "contextWrites":{
174 "#":{
175 "to":"..."
176 }
177 }
178}
179```
180
181<a name="createCharge"/>
182## Stripe.createCharge
183Method description
184
185| Field | Type | Description
186|--------------------|------------|----------
187| apiKey | credentials| The api key obtained from Stripe.
188| amount | String | A positive integer in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a 0-decimal currency) representing how much to charge the card. The minimum amount is $0.50 US or equivalent in charge currency.
189| currency | String | 3-letter ISO code for currency.
190| capture | String | 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.
191| description | String | 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.
192| receiptEmail | String | The email address to send this charge's receipt to. The receipt will not be sent until the charge is paid. If this charge is for a customer, the email address specified here will override the customer's email address. Receipts will not be sent for test mode charges. If `receipt_email` is specified for a charge in live mode, a receipt will be sent regardless of your email settings.
193| customer | String | The ID of an existing customer that will be charged in this request.
194| source | String | A payment source to be charged, such as a credit card. If you also pass a customer ID, the source must be the ID of a source belonging to the customer. Otherwise, if you do not pass a customer ID, the source you provide must either be a token, like the ones returned by Stripe.js, or a object containing a user's credit card details, with the options described below. Although not all information is required, the extra info helps prevent fraud.child attributes
195| statementDescriptor| String | An arbitrary string to be displayed on your customer`s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you`re charging for is a race ticket, you may want to specify a statement_descriptor of RunClub 5K race ticket. The statement description may not include <> characters, and will appear on your customer`s statement in capital letters. Non-ASCII characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all.
196
197#### Request example
198```json
199{ "apiKey": "...",
200 "amount": "...",
201 "currency": "...",
202 "capture": "...",
203 "description": "...",
204 "receiptEmail": "...",
205 "customer": "...",
206 "source": "...",
207 "statementDescriptor": "..."
208}
209```
210#### Response example
211```json
212{
213 "callback":"success",
214 "contextWrites":{
215 "#":{
216 "to":"..."
217 }
218 }
219}
220```
221
222<a name="createCustomer"/>
223## Stripe.createCustomer
224Method description
225
226| Field | Type | Description
227|---------------|------------|----------
228| apiKey | credentials| The api key obtained from Stripe.
229| source | String | The source can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below).child arguments
230| accountBalance| String | 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.
231| businessVatId | String | The customer’s VAT identification number. If you are using Relay, this field gets passed to tax provider you are using for your orders. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
232| coupon | String | 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.
233| description | String | 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 null and then saving.
234| email | String | 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 null and then saving.
235| metadata | JSON | 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 null and then saving.
236| plan | String | The identifier of the plan to subscribe the customer to. If provided, the returned customer object will have a list of subscriptions that the customer is currently subscribed to. If you subscribe a customer to a plan without a free trial, the customer must have a valid card as well.
237| taxPercent | String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice. Can only be used if a plan is provided.
238| trialEnd | String | Unix timestamp representing the end of the trial period the customer will get before being charged. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer’s trial immediately. Only applies when the plan parameter is also provided.
239
240#### Request example
241```json
242{ "apiKey": "...",
243 "source": "...",
244 "accountBalance": "...",
245 "businessVatId": "...",
246 "coupon": "...",
247 "description": "...",
248 "email": "...",
249 "metadata": "...",
250 "plan": "...",
251 "taxPercent": "...",
252 "trialEnd": "..."
253}
254```
255#### Response example
256```json
257{
258 "callback":"success",
259 "contextWrites":{
260 "#":{
261 "to":"..."
262 }
263 }
264}
265```
266
267<a name="getBalanceTransaction"/>
268## Stripe.getBalanceTransaction
269Method description
270
271| Field | Type | Description
272|-------|------------|----------
273| apiKey| credentials| The api key obtained from Stripe.
274| id | credentials| The ID of the desired balance transaction (as found on any API object that affects the balance, e.g. a charge or transfer).
275
276#### Request example
277```json
278{ "apiKey": "...",
279 "id": "..."
280}
281```
282#### Response example
283```json
284{
285 "callback":"success",
286 "contextWrites":{
287 "#":{
288 "to":"..."
289 }
290 }
291}
292```
293
294<a name="getCharge"/>
295## Stripe.getCharge
296Method description
297
298| Field | Type | Description
299|---------|------------|----------
300| apiKey | credentials| The api key obtained from Stripe.
301| chargeId| String | The identifier of the charge to be retrieved.
302
303#### Request example
304```json
305{ "apiKey": "...",
306 "chargeId": "..."
307}
308```
309#### Response example
310```json
311{
312 "callback":"success",
313 "contextWrites":{
314 "#":{
315 "to":"..."
316 }
317 }
318}
319```
320
321<a name="updateCharge"/>
322## Stripe.updateCharge
323Method description
324
325| Field | Type | Description
326|-------------|------------|----------
327| apiKey | credentials| The api key obtained from Stripe.
328| chargeId | String | Id of a charge.
329| description | String | 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.
330| receiptEmail| String | The email address to send this charge's receipt to. The receipt will not be sent until the charge is paid. If this charge is for a customer, the email address specified here will override the customer's email address. Receipts will not be sent for test mode charges. If `receipt_email` is specified for a charge in live mode, a receipt will be sent regardless of your email settings.
331| fraudDetails| JSON | A set of key/value pairs you can attach to a charge giving information about its riskiness. If you believe a charge is fraudulent, include a user_report key with a value of fraudulent. If you believe a charge is safe, include a user_report key with a value of safe. Note that you must refund a charge before setting the user_report to fraudulent. Stripe will use the information you send to improve our fraud detection algorithms.
332| metadata | JSON | 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 null and then saving. To clear all keys, set metadata to null, then save.
333| shipping | String | Shipping information for the charge. Helps prevent fraud on charges for physical goods.
334
335#### Request example
336```json
337{ "apiKey": "...",
338 "chargeId": "...",
339 "description": "...",
340 "receiptEmail": "...",
341 "fraudDetails": "...",
342 "metadata": "...",
343 "shipping": "..."
344}
345```
346#### Response example
347```json
348{
349 "callback":"success",
350 "contextWrites":{
351 "#":{
352 "to":"..."
353 }
354 }
355}
356```
357
358<a name="captureCharge"/>
359## Stripe.captureCharge
360Method description
361
362| Field | Type | Description
363|--------------------|------------|----------
364| apiKey | credentials| The api key obtained from Stripe.
365| chargeId | String | Id of a charge.
366| amount | String | The amount to capture, which must be less than or equal to the original amount. Any additional amount will be automatically refunded.
367| applicationFee | String | An application fee to add on to this charge. Can only be used with Stripe Connect.
368| receiptEmail | credentials| The email address to send this charge’s receipt to. This will override the previously-specified email address for this charge, if one was set. Receipts will not be sent in test mode.
369| statementDescriptor| credentials| An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you’re charging for is a race ticket, you may want to specify a statement_descriptor of RunClub 5K race ticket. The statement description may not include <> characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. Updating this value will overwrite the previous statement descriptor of this charge. While most banks display this information consistently, some may display it incorrectly or not at all
370
371#### Request example
372```json
373{ "apiKey": "...",
374 "chargeId": "...",
375 "amount": "...",
376 "applicationFee": "...",
377 "receiptEmail": "...",
378 "statementDescriptor": "..."
379}
380```
381#### Response example
382```json
383{
384 "callback":"success",
385 "contextWrites":{
386 "#":{
387 "to":"..."
388 }
389 }
390}
391```
392
393<a name="getChargesList"/>
394## Stripe.getChargesList
395Method description
396
397| Field | Type | Description
398|--------------|------------|----------
399| apiKey | credentials| The api key obtained from Stripe.
400| created | String | A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options: child arguments
401| customer | String | Only return charges for the customer specified by this customer ID.
402| endingBefore | String | 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.
403| limit | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
404| source | String | A filter on the list based on the source of the charge. The value can be a dictionary with the following options:
405| startingAfter| String | 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.
406
407#### Request example
408```json
409{ "apiKey": "...",
410 "created": "...",
411 "customer": "...",
412 "endingBefore": "...",
413 "limit": "...",
414 "source": "...",
415 "startingAfter": "..."
416}
417```
418#### Response example
419```json
420{
421 "callback":"success",
422 "contextWrites":{
423 "#":{
424 "to":"..."
425 }
426 }
427}
428```
429
430<a name="getCustomer"/>
431## Stripe.getCustomer
432Method description
433
434| Field | Type | Description
435|-----------|------------|----------
436| apiKey | credentials| The api key obtained from Stripe.
437| customerId| String | The identifier of the customer to be retrieved.
438
439#### Request example
440```json
441{ "apiKey": "...",
442 "customerId": "..."
443}
444```
445#### Response example
446```json
447{
448 "callback":"success",
449 "contextWrites":{
450 "#":{
451 "to":"..."
452 }
453 }
454}
455```
456
457<a name="updateCustomer"/>
458## Stripe.updateCustomer
459Method description
460
461| Field | Type | Description
462|---------------|------------|----------
463| apiKey | credentials| The api key obtained from Stripe.
464| customerId | String | If of customer to update.
465| source | String | The source can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below).child arguments
466| accountBalance| String | 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.
467| businessVatId | String | The customer’s VAT identification number. If you are using Relay, this field gets passed to tax provider you are using for your orders. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
468| coupon | String | 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.
469| description | String | 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 null and then saving.
470| email | String | 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 null and then saving.
471| metadata | JSON | 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 null and then saving.
472| plan | String | The identifier of the plan to subscribe the customer to. If provided, the returned customer object will have a list of subscriptions that the customer is currently subscribed to. If you subscribe a customer to a plan without a free trial, the customer must have a valid card as well.
473| taxPercent | String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice. Can only be used if a plan is provided.
474| trialEnd | String | Unix timestamp representing the end of the trial period the customer will get before being charged. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer’s trial immediately. Only applies when the plan parameter is also provided.
475
476#### Request example
477```json
478{ "apiKey": "...",
479 "customerId": "...",
480 "source": "...",
481 "accountBalance": "...",
482 "businessVatId": "...",
483 "coupon": "...",
484 "description": "...",
485 "email": "...",
486 "metadata": "...",
487 "plan": "...",
488 "taxPercent": "...",
489 "trialEnd": "..."
490}
491```
492#### Response example
493```json
494{
495 "callback":"success",
496 "contextWrites":{
497 "#":{
498 "to":"..."
499 }
500 }
501}
502```
503
504<a name="getBalanceTransaction"/>
505## Stripe.getBalanceTransaction
506Method description
507
508| Field | Type | Description
509|-------|------------|----------
510| apiKey| credentials| The api key obtained from Stripe.
511| id | credentials| The ID of the desired balance transaction (as found on any API object that affects the balance, e.g. a charge or transfer).
512
513#### Request example
514```json
515{ "apiKey": "...",
516 "id": "..."
517}
518```
519#### Response example
520```json
521{
522 "callback":"success",
523 "contextWrites":{
524 "#":{
525 "to":"..."
526 }
527 }
528}
529```
530
531<a name="deleteCustomer"/>
532## Stripe.deleteCustomer
533Method description
534
535| Field | Type | Description
536|-----------|------------|----------
537| apiKey | credentials| The api key obtained from Stripe.
538| customerId| String | If of customer to update.
539
540#### Request example
541```json
542{ "apiKey": "...",
543 "customerId": "..."
544}
545```
546#### Response example
547```json
548{
549 "callback":"success",
550 "contextWrites":{
551 "#":{
552 "to":"..."
553 }
554 }
555}
556```
557
558<a name="getCustomerList"/>
559## Stripe.getCustomerList
560Method description
561
562| Field | Type | Description
563|-------|------------|----------
564| apiKey| credentials| The api key obtained from Stripe.
565
566#### Request example
567```json
568{ "apiKey": "..."
569}
570```
571#### Response example
572```json
573{
574 "callback":"success",
575 "contextWrites":{
576 "#":{
577 "to":"..."
578 }
579 }
580}
581```
582
583<a name="getDispute"/>
584## Stripe.getDispute
585Method description
586
587| Field | Type | Description
588|----------|------------|----------
589| apiKey | credentials| The api key obtained from Stripe.
590| disputeId| String | ID of dispute to retrieve.
591
592#### Request example
593```json
594{ "apiKey": "...",
595 "disputeId": "..."
596}
597```
598#### Response example
599```json
600{
601 "callback":"success",
602 "contextWrites":{
603 "#":{
604 "to":"..."
605 }
606 }
607}
608```
609
610<a name="updateDispute"/>
611## Stripe.updateDispute
612Method description
613
614| Field | Type | Description
615|----------|------------|----------
616| apiKey | credentials| The api key obtained from Stripe.
617| disputeId| String | ID of dispute to retrieve.
618| evidence | JSON | Evidence to upload to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review.
619| metadata | JSON | A set of key/value pairs that you can attach to a dispute object. It can be useful for storing additional information about the dispute in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
620
621#### Request example
622```json
623{ "apiKey": "...",
624 "disputeId": "...",
625 "evidence": "...",
626 "metadata": "..."
627}
628```
629#### Response example
630```json
631{
632 "callback":"success",
633 "contextWrites":{
634 "#":{
635 "to":"..."
636 }
637 }
638}
639```
640
641<a name="closeDispute"/>
642## Stripe.closeDispute
643Method description
644
645| Field | Type | Description
646|----------|------------|----------
647| apiKey | credentials| The api key obtained from Stripe.
648| disputeId| String | ID of dispute to retrieve.
649
650#### Request example
651```json
652{ "apiKey": "...",
653 "disputeId": "..."
654}
655```
656#### Response example
657```json
658{
659 "callback":"success",
660 "contextWrites":{
661 "#":{
662 "to":"..."
663 }
664 }
665}
666```
667
668<a name="getDisputes"/>
669## Stripe.getDisputes
670Method description
671
672| Field | Type | Description
673|-------|------------|----------
674| apiKey| credentials| The api key obtained from Stripe.
675
676#### Request example
677```json
678{ "apiKey": "..."
679}
680```
681#### Response example
682```json
683{
684 "callback":"success",
685 "contextWrites":{
686 "#":{
687 "to":"..."
688 }
689 }
690}
691```
692
693<a name="getEvent"/>
694## Stripe.getEvent
695Method description
696
697| Field | Type | Description
698|--------|------------|----------
699| apiKey | credentials| The api key obtained from Stripe.
700| eventId| credentials| The api key obtained from Stripe.
701
702#### Request example
703```json
704{ "apiKey": "...",
705 "eventId": "..."
706}
707```
708#### Response example
709```json
710{
711 "callback":"success",
712 "contextWrites":{
713 "#":{
714 "to":"..."
715 }
716 }
717}
718```
719
720<a name="getEventList"/>
721## Stripe.getEventList
722Method description
723
724| Field | Type | Description
725|-------|------------|----------
726| apiKey| credentials| The api key obtained from Stripe.
727| type | String | A string containing a specific event name, or group of events using * as a wildcard. The list will be filtered to include only events with a matching event property.
728
729#### Request example
730```json
731{ "apiKey": "...",
732 "type": "..."
733}
734```
735#### Response example
736```json
737{
738 "callback":"success",
739 "contextWrites":{
740 "#":{
741 "to":"..."
742 }
743 }
744}
745```
746
747<a name="createFileUpload"/>
748## Stripe.createFileUpload
749Method description
750
751| Field | Type | Description
752|--------|------------|----------
753| apiKey | credentials| The api key obtained from Stripe.
754| file | String | A file to upload.
755| purpose| String | The purpoe of the uploaded file. Possible values are `business_logo`, `dispute_evidence`, `identity_document`, `incorporation_article`, `incorporation_document`, `payment_provider_transfer`, `product_feed`.
756
757#### Request example
758```json
759{ "apiKey": "...",
760 "file": "...",
761 "purpose": "..."
762}
763```
764#### Response example
765```json
766{
767 "callback":"success",
768 "contextWrites":{
769 "#":{
770 "to":"..."
771 }
772 }
773}
774```
775
776<a name="createRefund"/>
777## Stripe.createRefund
778Method description
779
780| Field | Type | Description
781|---------------------|------------|----------
782| apiKey | credentials| The api key obtained from Stripe.
783| chargeId | String | The identifier of the charge to refund.
784| amount | String | 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.
785| metadata | JSON | A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
786| reason | String | String indicating the reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer. Specifying fraudulent as the reason when you believe the charge to be fraudulent will help us improve our fraud detection algorithms.
787| refundApplicationFee| String | 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.
788| reverseTransfer | String | Boolean indicating whether the transfer should be reversed when refunding this charge. The transfer will be reversed for the same amount being refunded (either the entire or partial amount). A transfer can only be reversed by the application that created the charge.
789
790#### Request example
791```json
792{ "apiKey": "...",
793 "chargeId": "...",
794 "amount": "...",
795 "metadata": "...",
796 "reason": "...",
797 "refundApplicationFee": "...",
798 "reverseTransfer": "..."
799}
800```
801#### Response example
802```json
803{
804 "callback":"success",
805 "contextWrites":{
806 "#":{
807 "to":"..."
808 }
809 }
810}
811```
812
813<a name="getRefund"/>
814## Stripe.getRefund
815Method description
816
817| Field | Type | Description
818|---------|------------|----------
819| apiKey | credentials| The api key obtained from Stripe.
820| refundId| String | ID of refund to retrieve.
821
822#### Request example
823```json
824{ "apiKey": "...",
825 "refundId": "..."
826}
827```
828#### Response example
829```json
830{
831 "callback":"success",
832 "contextWrites":{
833 "#":{
834 "to":"..."
835 }
836 }
837}
838```
839
840<a name="updateRefund"/>
841## Stripe.updateRefund
842Method description
843
844| Field | Type | Description
845|---------|------------|----------
846| apiKey | credentials| The api key obtained from Stripe.
847| refundId| String | ID of refund to retrieve.
848| metadata| JSON | A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
849
850#### Request example
851```json
852{ "apiKey": "...",
853 "refundId": "...",
854 "metadata": "..."
855}
856```
857#### Response example
858```json
859{
860 "callback":"success",
861 "contextWrites":{
862 "#":{
863 "to":"..."
864 }
865 }
866}
867```
868
869<a name="getRefundList"/>
870## Stripe.getRefundList
871Method description
872
873| Field | Type | Description
874|-------|------------|----------
875| apiKey| credentials| The api key obtained from Stripe.
876
877#### Request example
878```json
879{ "apiKey": "..."
880}
881```
882#### Response example
883```json
884{
885 "callback":"success",
886 "contextWrites":{
887 "#":{
888 "to":"..."
889 }
890 }
891}
892```
893
894<a name="createCardToken"/>
895## Stripe.createCardToken
896Method description
897
898| Field | Type | Description
899|--------------------|------------|----------
900| apiKey | credentials| The api key obtained from Stripe.
901| cardNumber | String | Number of card
902| cardExpirationMonth| Number | Expiration month of card
903| cardExpirationYear | Number | Expiration year of card
904| cardCvc | String | CVC code of card
905
906#### Request example
907```json
908{ "apiKey": "...",
909 "cardNumber": "...",
910 "cardExpirationMonth": 0,
911 "cardExpirationYear": 0,
912 "cardCvc": "..."
913}
914```
915#### Response example
916```json
917{
918 "callback":"success",
919 "contextWrites":{
920 "#":{
921 "to":"..."
922 }
923 }
924}
925```
926
927<a name="createBankAccountToken"/>
928## Stripe.createBankAccountToken
929Method description
930
931| Field | Type | Description
932|-----------------------------|------------|----------
933| apiKey | credentials| The api key obtained from Stripe.
934| bankAccountCountry | String | The bank account country
935| bankAccountCurrency | String | The bank account currency
936| bankAccountAccountHolderName| String | The bank account holder name
937| bankAccountAccountHolderType| String | The bank account holder type
938| bankAccountRoutingNumber | String | The bank account routing number
939| bankAccountNumber | String | The bank account number
940
941#### Request example
942```json
943{ "apiKey": "...",
944 "bankAccountCountry": "...",
945 "bankAccountCurrency": "...",
946 "bankAccountAccountHolderName": "...",
947 "bankAccountAccountHolderType": "...",
948 "bankAccountRoutingNumber": "...",
949 "bankAccountNumber": "..."
950}
951```
952#### Response example
953```json
954{
955 "callback":"success",
956 "contextWrites":{
957 "#":{
958 "to":"..."
959 }
960 }
961}
962```
963
964<a name="createPiiToken"/>
965## Stripe.createPiiToken
966Method description
967
968| Field | Type | Description
969|-----------------|------------|----------
970| apiKey | credentials| The api key obtained from Stripe.
971| personalIdNumber| String | The bank account country
972
973#### Request example
974```json
975{ "apiKey": "...",
976 "personalIdNumber": "..."
977}
978```
979#### Response example
980```json
981{
982 "callback":"success",
983 "contextWrites":{
984 "#":{
985 "to":"..."
986 }
987 }
988}
989```
990
991<a name="getToken"/>
992## Stripe.getToken
993Method description
994
995| Field | Type | Description
996|--------|------------|----------
997| apiKey | credentials| The api key obtained from Stripe.
998| tokenId| String | The ID of the desired token.
999
1000#### Request example
1001```json
1002{ "apiKey": "...",
1003 "tokenId": "..."
1004}
1005```
1006#### Response example
1007```json
1008{
1009 "callback":"success",
1010 "contextWrites":{
1011 "#":{
1012 "to":"..."
1013 }
1014 }
1015}
1016```
1017
1018<a name="createTransfer"/>
1019## Stripe.createTransfer
1020Method description
1021
1022| Field | Type | Description
1023|--------------------|------------|----------
1024| apiKey | credentials| The api key obtained from Stripe.
1025| amount | Number | A positive integer in cents representing how much to transfer.
1026| currency | String | 3-letter ISO code for currency
1027| destination | String | The id of a bank account or a card to send the transfer to, or the string `default_for_currency` to use the default external account for the specified currency.
1028| description | String | An arbitrary string which you can attach to a transfer object. It is displayed when in the web interface alongside the transfer.
1029| sourceTransaction | String | You can use this parameter to transfer funds from a charge (or other transaction) before they are added to your available balance. A pending balance will transfer immediately but the funds will not become available until the original charge becomes available.
1030| statementDescriptor| String | A string to be displayed on the recipient's bank or card statement. This may be at most 22 characters. Attempting to use a statement_descriptor longer than 22 characters will return an error. Note: Most banks will truncate this information and/or display it inconsistently. Some may not display it at all.
1031| sourceType | String | Valid options are: alipay_account, bank_account, bitcoin_receiver, and card.
1032
1033#### Request example
1034```json
1035{ "apiKey": "...",
1036 "amount": 0,
1037 "currency": "...",
1038 "destination": "...",
1039 "description": "...",
1040 "sourceTransaction": "...",
1041 "statementDescriptor": "...",
1042 "sourceType": "..."
1043}
1044```
1045#### Response example
1046```json
1047{
1048 "callback":"success",
1049 "contextWrites":{
1050 "#":{
1051 "to":"..."
1052 }
1053 }
1054}
1055```
1056
1057<a name="getTransfer"/>
1058## Stripe.getTransfer
1059Method description
1060
1061| Field | Type | Description
1062|-----------|------------|----------
1063| apiKey | credentials| The api key obtained from Stripe.
1064| transferId| String | The identifier of the transfer to be retrieved.
1065
1066#### Request example
1067```json
1068{ "apiKey": "...",
1069 "transferId": "..."
1070}
1071```
1072#### Response example
1073```json
1074{
1075 "callback":"success",
1076 "contextWrites":{
1077 "#":{
1078 "to":"..."
1079 }
1080 }
1081}
1082```
1083
1084<a name="updateTransfer"/>
1085## Stripe.updateTransfer
1086Method description
1087
1088| Field | Type | Description
1089|------------|------------|----------
1090| apiKey | credentials| The api key obtained from Stripe.
1091| transferId | String | Id of transfer to update.
1092| description| String | An arbitrary string which you can attach to a transfer object. It is displayed when in the web interface alongside the transfer. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
1093| metadata | JSON | 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 null and then saving. To clear all keys, set metadata to null, then save.
1094
1095#### Request example
1096```json
1097{ "apiKey": "...",
1098 "transferId": "...",
1099 "description": "...",
1100 "metadata": "..."
1101}
1102```
1103#### Response example
1104```json
1105{
1106 "callback":"success",
1107 "contextWrites":{
1108 "#":{
1109 "to":"..."
1110 }
1111 }
1112}
1113```
1114
1115<a name="getTransferList"/>
1116## Stripe.getTransferList
1117Method description
1118
1119| Field | Type | Description
1120|----------------|------------|----------
1121| apiKey | credentials| The api key obtained from Stripe.
1122| destination | String | Only return transfers for the destination specified by this account ID.
1123| recipientstatus| String | Only return transfers for the recipient specified by this recipient ID.
1124| status | String | Only return transfers that have the given status: `pending`, `paid`, `failed`, `in_transit`, or `canceled`.
1125
1126#### Request example
1127```json
1128{ "apiKey": "...",
1129 "destination": "...",
1130 "recipientstatus": "...",
1131 "status": "..."
1132}
1133```
1134#### Response example
1135```json
1136{
1137 "callback":"success",
1138 "contextWrites":{
1139 "#":{
1140 "to":"..."
1141 }
1142 }
1143}
1144```# Stripe Package
1145This blocks allows you to translates a sting of text from one language to another
1146* Domain: stripe.com
1147* Credentials: apiKey.
1148
1149## How to get credentials:
11500. Sign in [stripe dashboard](https://dashboard.stripe.com/dashboard).
11511. Go to [your account settings](https://dashboard.stripe.com/account).
11522. Choose [*API Keys* folder](https://dashboard.stripe.com/account/apikeys).
11533. Copy and save your *Secret Key*.
1154
1155## TOC:
1156* [getAccountBalance](#getAccountBalance)
1157* [getBalanceHistory](#getBalanceHistory)
1158* [createCharge](#createCharge)
1159* [createCustomer](#createCustomer)
1160* [getBalanceTransaction](#getBalanceTransaction)
1161* [getCharge](#getCharge)
1162* [updateCharge](#updateCharge)
1163* [captureCharge](#captureCharge)
1164* [getChargesList](#getChargesList)
1165* [getCustomer](#getCustomer)
1166* [updateCustomer](#updateCustomer)
1167* [getBalanceTransaction](#getBalanceTransaction)
1168* [deleteCustomer](#deleteCustomer)
1169* [getCustomerList](#getCustomerList)
1170* [getDispute](#getDispute)
1171* [updateDispute](#updateDispute)
1172* [closeDispute](#closeDispute)
1173* [getDisputes](#getDisputes)
1174* [getEvent](#getEvent)
1175* [getEventList](#getEventList)
1176* [createFileUpload](#createFileUpload)
1177* [createRefund](#createRefund)
1178* [getRefund](#getRefund)
1179* [updateRefund](#updateRefund)
1180* [getRefundList](#getRefundList)
1181* [createCardToken](#createCardToken)
1182* [createBankAccountToken](#createBankAccountToken)
1183* [createPiiToken](#createPiiToken)
1184* [getToken](#getToken)
1185* [createTransfer](#createTransfer)
1186* [getTransfer](#getTransfer)
1187* [updateTransfer](#updateTransfer)
1188* [getTransferList](#getTransferList)
1189* [createTransferReversal](#createTransferReversal)
1190* [getTransferReversal](#getTransferReversal)
1191* [updateTransferReversal](#updateTransferReversal)
1192* [getTransferReversalList](#getTransferReversalList)
1193* [createAccount](#createAccount)
1194* [getAccount](#getAccount)
1195* [updateAccount](#updateAccount)
1196* [deleteAccount](#deleteAccount)
1197* [rejectAccount](#rejectAccount)
1198* [getAccountList](#getAccountList)
1199* [createFeeRefund](#createFeeRefund)
1200* [getFeeRefund](#getFeeRefund)
1201* [updateFeeRefund](#updateFeeRefund)
1202* [getFeeRefundList](#getFeeRefundList)
1203* [getApplicationFee](#getApplicationFee)
1204* [getApplicationFeeList](#getApplicationFeeList)
1205* [getCountrySpecsList](#getCountrySpecsList)
1206* [getCountrySpec](#getCountrySpec)
1207* [createBankAccount](#createBankAccount)
1208* [getBankAccount](#getBankAccount)
1209* [updateBankAccount](#updateBankAccount)
1210* [deleteBankAccount](#deleteBankAccount)
1211* [getBankAccountList](#getBankAccountList)
1212* [createCard](#createCard)
1213* [getCard](#getCard)
1214* [updateCard](#updateCard)
1215* [deleteCard](#deleteCard)
1216* [getCardList](#getCardList)
1217* [createReceiver](#createReceiver)
1218* [getReceiver](#getReceiver)
1219* [getReceiverList](#getReceiverList)
1220* [createOrder](#createOrder)
1221* [getOrder](#getOrder)
1222* [updateOrder](#updateOrder)
1223* [payOrder](#payOrder)
1224* [getOrderList](#getOrderList)
1225* [returnOrder](#returnOrder)
1226* [getOrderReturn](#getOrderReturn)
1227* [getOrderReturnList](#getOrderReturnList)
1228* [createProduct](#createProduct)
1229* [getProduct](#getProduct)
1230* [updateProduct](#updateProduct)
1231* [getProductList](#getProductList)
1232* [deleteProduct](#deleteProduct)
1233* [createSKU](#createSKU)
1234* [getSKU](#getSKU)
1235* [updateSKU](#updateSKU)
1236* [getSKUList](#getSKUList)
1237* [deleteSKU](#deleteSKU)
1238* [createCoupon](#createCoupon)
1239* [getCoupon](#getCoupon)
1240* [updateCoupon](#updateCoupon)
1241* [deleteCoupon](#deleteCoupon)
1242* [getCouponList](#getCouponList)
1243* [deleteCustomerDiscount](#deleteCustomerDiscount)
1244* [deleteSubscriptionDiscount](#deleteSubscriptionDiscount)
1245* [createInvoice](#createInvoice)
1246* [getInvoice](#getInvoice)
1247* [getInvoiceLineItems](#getInvoiceLineItems)
1248* [updateInvoice](#updateInvoice)
1249* [payInvoice](#payInvoice)
1250* [getInvoiceList](#getInvoiceList)
1251* [getInvoiceList](#getInvoiceList)
1252* [createInvoiceItem](#createInvoiceItem)
1253* [getInvoiceItem](#getInvoiceItem)
1254* [updateInvoiceItem](#updateInvoiceItem)
1255* [deleteInvoiceItem](#deleteInvoiceItem)
1256* [getInvoiceItemsList](#getInvoiceItemsList)
1257* [createPlan](#createPlan)
1258* [getPlan](#getPlan)
1259* [updatePlan](#updatePlan)
1260* [deletePlan](#deletePlan)
1261* [getPlanList](#getPlanList)
1262* [createSubscription](#createSubscription)
1263* [getSubscription](#getSubscription)
1264* [updateSubscription](#updateSubscription)
1265* [cancelSubscription](#cancelSubscription)
1266* [getSubscriptionList](#getSubscriptionList)
1267
1268<a name="getAccountBalance"/>
1269## Stripe.getAccountBalance
1270Retrieves the current account balance, based on the authentication that was used to make the request.
1271
1272| Field | Type | Description
1273|-------|------------|----------
1274| apiKey| credentials| The api key obtained from Stripe.
1275
1276#### Request example
1277```json
1278{
1279 "apiKey": "..."
1280}
1281```
1282#### Response example
1283```json
1284{
1285 "callback":"success",
1286 "contextWrites":{
1287 "#":{
1288 "to": {
1289 "object": "balance",
1290 "available": [
1291 {
1292 "currency": "aud",
1293 "amount": -88,
1294 "source_types": {
1295 "card": -88
1296 }
1297 },
1298 {
1299 "currency": "jpy",
1300 "amount": -40320,
1301 "source_types": {
1302 "card": -40320
1303 }
1304 },
1305 {
1306 "currency": "usd",
1307 "amount": 13702549683,
1308 "source_types": {
1309 "card": 13598002733,
1310 "bank_account": 103002760,
1311 "bitcoin_receiver": 1544190
1312 }
1313 }
1314 ],
1315 "livemode": false,
1316 "pending": [
1317 {
1318 "currency": "aud",
1319 "amount": 0,
1320 "source_types": {
1321 "card": 0
1322 }
1323 },
1324 {
1325 "currency": "jpy",
1326 "amount": 0,
1327 "source_types": {
1328 "card": 0
1329 }
1330 },
1331 {
1332 "currency": "usd",
1333 "amount": 396093624,
1334 "source_types": {
1335 "card": 396093624,
1336 "bank_account": 0,
1337 "bitcoin_receiver": 0
1338 }
1339 }
1340 ]
1341 }
1342 }
1343 }
1344}
1345```
1346
1347<a name="getBalanceHistory"/>
1348## Stripe.getBalanceHistory
1349Returns a list of transactions that have contributed to the Stripe account balance (e.g., charges, transfers, and so forth). The transactions are returned in sorted order, with the most recent transactions appearing first.
1350
1351| Field | Type | Description
1352|--------------|------------|----------
1353| apiKey | credentials| The api key obtained from Stripe.
1354| currency | String | 3-letter ISO code for currency.
1355| startingAfter| String | 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.
1356| limit | Number | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
1357| type | String | Only returns transactions of the given type. One of: `charge`, `refund`, `adjustment`, `application_fee`, `application_fee_refund`, `transfer`, or `transfer_failure`
1358
1359#### Request example
1360```json
1361{
1362 "apiKey": "...",
1363 "currency": "usd",
1364 "startingAfter": "...",
1365 "limit": 3,
1366 "type": "..."
1367}
1368```
1369#### Response example
1370```json
1371{
1372 "callback":"success",
1373 "contextWrites":{
1374 "#":{
1375 "to": {
1376 "object": "list",
1377 "url": "/v1/balance/history",
1378 "has_more": false,
1379 "data": [
1380 {
1381 "id": "txn_18tiU12eZvKYlo2CetxoRTDG",
1382 "object": "balance_transaction",
1383 "amount": 5001,
1384 "available_on": 1474416000,
1385 "created": 1473879105,
1386 "currency": "usd",
1387 "description": "User: 813. Events: 1267. Total Tickets: 1.",
1388 "fee": 175,
1389 "fee_details": [
1390 {
1391 "amount": 175,
1392 "application": null,
1393 "currency": "usd",
1394 "description": "Stripe processing fees",
1395 "type": "stripe_fee"
1396 }
1397 ],
1398 "net": 4826,
1399 "source": "ch_18tiU12eZvKYlo2CliINmYLR",
1400 "sourced_transfers": {
1401 "object": "list",
1402 "data": [],
1403 "has_more": false,
1404 "total_count": 0,
1405 "url": "/v1/transfers?source_transaction=ch_18tiU12eZvKYlo2CliINmYLR"
1406 },
1407 "status": "pending",
1408 "type": "charge"
1409 },
1410 {...},
1411 {...}
1412 ]
1413 }
1414 }
1415 }
1416}
1417```
1418
1419<a name="createCharge"/>
1420## Stripe.createCharge
1421To charge a credit card, you create a charge object. If your API key is in test mode, the supplied payment source (e.g., card or Bitcoin receiver) won't actually be charged, though everything else will occur as if in live mode. (Stripe assumes that the charge would have completed successfully).
1422
1423| Field | Type | Description
1424|--------------------|------------|----------
1425| apiKey | credentials| The api key obtained from Stripe.
1426| amount | String | A positive integer in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a 0-decimal currency) representing how much to charge the card. The minimum amount is $0.50 US or equivalent in charge currency.
1427| currency | String | 3-letter ISO code for currency.
1428| capture | String | 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.
1429| description | String | 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.
1430| receiptEmail | String | The email address to send this charge's receipt to. The receipt will not be sent until the charge is paid. If this charge is for a customer, the email address specified here will override the customer's email address. Receipts will not be sent for test mode charges. If `receipt_email` is specified for a charge in live mode, a receipt will be sent regardless of your email settings.
1431| customer | String | The ID of an existing customer that will be charged in this request.
1432| source | String | A payment source to be charged, such as a credit card. If you also pass a customer ID, the source must be the ID of a source belonging to the customer. Otherwise, if you do not pass a customer ID, the source you provide must either be a token, like the ones returned by Stripe.js, or a object containing a user's credit card details, with the options described below. Although not all information is required, the extra info helps prevent fraud.child attributes
1433| statementDescriptor| String | An arbitrary string to be displayed on your customer`s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you`re charging for is a race ticket, you may want to specify a statement_descriptor of RunClub 5K race ticket. The statement description may not include <> characters, and will appear on your customer`s statement in capital letters. Non-ASCII characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all.
1434
1435#### Request example
1436```json
1437{
1438 "apiKey": "...",
1439 "amount": 2000,
1440 "currency": "usd",
1441 "source": "tok_189fTS2eZvKYlo2CcYJIOGkr",
1442}
1443```
1444#### Response example
1445```json
1446{
1447 "callback":"success",
1448 "contextWrites":{
1449 "#":{
1450 "to": {
1451 "id": "ch_18zQ402eZvKYlo2CvQYLBOJ4",
1452 "object": "charge",
1453 "amount": 999,
1454 "amount_refunded": 0,
1455 "application_fee": null,
1456 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
1457 "captured": true,
1458 "created": 1475238268,
1459 "currency": "usd",
1460 "customer": "cus_96kH68CmcC5XcM",
1461 "description": null,
1462 "destination": null,
1463 "dispute": null,
1464 "failure_code": null,
1465 "failure_message": null,
1466 "fraud_details": {
1467 },
1468 "invoice": "in_18zP7g2eZvKYlo2CUqGHFAlX",
1469 "livemode": false,
1470 "metadata": {
1471 },
1472 "order": null,
1473 "paid": true,
1474 "receipt_email": null,
1475 "receipt_number": null,
1476 "refunded": false,
1477 "refunds": {
1478 "object": "list",
1479 "data": [
1480
1481 ],
1482 "has_more": false,
1483 "total_count": 0,
1484 "url": "/v1/charges/ch_18zQ402eZvKYlo2CvQYLBOJ4/refunds"
1485 },
1486 "shipping": null,
1487 "source": {
1488 "id": "card_18oWmJ2eZvKYlo2CApIJRrtd",
1489 "object": "card",
1490 "address_city": null,
1491 "address_country": null,
1492 "address_line1": null,
1493 "address_line1_check": null,
1494 "address_line2": null,
1495 "address_state": null,
1496 "address_zip": null,
1497 "address_zip_check": null,
1498 "brand": "Visa",
1499 "country": "US",
1500 "customer": "cus_96kH68CmcC5XcM",
1501 "cvc_check": null,
1502 "dynamic_last4": null,
1503 "exp_month": 12,
1504 "exp_year": 2017,
1505 "funding": "credit",
1506 "last4": "4242",
1507 "metadata": {
1508 },
1509 "name": null,
1510 "tokenization_method": null
1511 },
1512 "source_transfer": null,
1513 "statement_descriptor": null,
1514 "status": "succeeded"
1515 }
1516 }
1517 }
1518}
1519```
1520
1521<a name="createCustomer"/>
1522## Stripe.createCustomer
1523Creates a new customer object.
1524
1525| Field | Type | Description
1526|---------------|------------|----------
1527| apiKey | credentials| The api key obtained from Stripe.
1528| source | String | The source can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below).child arguments
1529| accountBalance| String | 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.
1530| businessVatId | String | The customer’s VAT identification number. If you are using Relay, this field gets passed to tax provider you are using for your orders. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
1531| coupon | String | 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.
1532| description | String | 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 null and then saving.
1533| email | String | 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 null and then saving.
1534| metadata | JSON | 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 null and then saving.
1535| plan | String | The identifier of the plan to subscribe the customer to. If provided, the returned customer object will have a list of subscriptions that the customer is currently subscribed to. If you subscribe a customer to a plan without a free trial, the customer must have a valid card as well.
1536| taxPercent | String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice. Can only be used if a plan is provided.
1537| trialEnd | String | Unix timestamp representing the end of the trial period the customer will get before being charged. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer’s trial immediately. Only applies when the plan parameter is also provided.
1538
1539#### Request example
1540```json
1541{
1542 "apiKey": "...",
1543 "source": "tok_189fTS2eZvKYlo2CcYJIOGkr",
1544 "description": "Customer for andrew.martinez@example.com",
1545}
1546```
1547#### Response example
1548```json
1549{
1550 "callback":"success",
1551 "contextWrites":{
1552 "#":{
1553 "to": {
1554 "id": "cus_9I04eaA61hXf5W",
1555 "object": "customer",
1556 "account_balance": 0,
1557 "created": 1475238307,
1558 "currency": "usd",
1559 "default_source": "card_18zQ422eZvKYlo2CIznAqoaV",
1560 "delinquent": false,
1561 "description": "Emily Martin",
1562 "discount": null,
1563 "email": "emily.martin.57@example.com",
1564 "livemode": false,
1565 "metadata": {
1566 },
1567 "shipping": null,
1568 "sources": {
1569 "object": "list",
1570 "data": [
1571 {
1572 "id": "card_18zQ422eZvKYlo2CIznAqoaV",
1573 "object": "card",
1574 "address_city": null,
1575 "address_country": null,
1576 "address_line1": null,
1577 "address_line1_check": null,
1578 "address_line2": null,
1579 "address_state": null,
1580 "address_zip": null,
1581 "address_zip_check": null,
1582 "brand": "Visa",
1583 "country": "US",
1584 "customer": "cus_9I04eaA61hXf5W",
1585 "cvc_check": "pass",
1586 "dynamic_last4": null,
1587 "exp_month": 12,
1588 "exp_year": 2017,
1589 "funding": "credit",
1590 "last4": "4242",
1591 "metadata": {
1592 },
1593 "name": null,
1594 "tokenization_method": null
1595 }
1596 ],
1597 "has_more": false,
1598 "total_count": 1,
1599 "url": "/v1/customers/cus_9I04eaA61hXf5W/sources"
1600 },
1601 "subscriptions": {
1602 "object": "list",
1603 "data": [
1604
1605 ],
1606 "has_more": false,
1607 "total_count": 0,
1608 "url": "/v1/customers/cus_9I04eaA61hXf5W/subscriptions"
1609 }
1610 }
1611 }
1612 }
1613}
1614```
1615
1616<a name="getBalanceTransaction"/>
1617## Stripe.getBalanceTransaction
1618Retrieves the balance transaction with the given ID.
1619
1620| Field | Type | Description
1621|-------|------------|----------
1622| apiKey| credentials| The api key obtained from Stripe.
1623| id | credentials| The ID of the desired balance transaction (as found on any API object that affects the balance, e.g. a charge or transfer).
1624
1625#### Request example
1626```json
1627{
1628 "apiKey": "...",
1629 "id": "txn_18tiU12eZvKYlo2CetxoRTDG"
1630}
1631```
1632#### Response example
1633```json
1634{
1635 "callback":"success",
1636 "contextWrites":{
1637 "#":{
1638 "to": {
1639 "id": "txn_18tiU12eZvKYlo2CetxoRTDG",
1640 "object": "balance_transaction",
1641 "amount": 5001,
1642 "available_on": 1474416000,
1643 "created": 1473879105,
1644 "currency": "usd",
1645 "description": "User: 813. Events: 1267. Total Tickets: 1.",
1646 "fee": 175,
1647 "fee_details": [
1648 {
1649 "amount": 175,
1650 "application": null,
1651 "currency": "usd",
1652 "description": "Stripe processing fees",
1653 "type": "stripe_fee"
1654 }
1655 ],
1656 "net": 4826,
1657 "source": "ch_18tiU12eZvKYlo2CliINmYLR",
1658 "sourced_transfers": {
1659 "object": "list",
1660 "data": [
1661
1662 ],
1663 "has_more": false,
1664 "total_count": 0,
1665 "url": "/v1/transfers?source_transaction=ch_18tiU12eZvKYlo2CliINmYLR"
1666 },
1667 "status": "pending",
1668 "type": "charge"
1669 }
1670 }
1671 }
1672}
1673```
1674
1675<a name="getCharge"/>
1676## Stripe.getCharge
1677Retrieves 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.
1678
1679| Field | Type | Description
1680|---------|------------|----------
1681| apiKey | credentials| The api key obtained from Stripe.
1682| chargeId| String | The identifier of the charge to be retrieved.
1683
1684#### Request example
1685```json
1686{
1687 "apiKey": "...",
1688 "chargeId": "ch_18zQ402eZvKYlo2CvQYLBOJ4"
1689}
1690```
1691#### Response example
1692```json
1693{
1694 "callback":"success",
1695 "contextWrites":{
1696 "#":{
1697 "to": {
1698 "id": "ch_18zQ402eZvKYlo2CvQYLBOJ4",
1699 "object": "charge",
1700 "amount": 999,
1701 "amount_refunded": 0,
1702 "application_fee": null,
1703 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
1704 "captured": true,
1705 "created": 1475238268,
1706 "currency": "usd",
1707 "customer": "cus_96kH68CmcC5XcM",
1708 "description": null,
1709 "destination": null,
1710 "dispute": null,
1711 "failure_code": null,
1712 "failure_message": null,
1713 "fraud_details": {
1714 },
1715 "invoice": "in_18zP7g2eZvKYlo2CUqGHFAlX",
1716 "livemode": false,
1717 "metadata": {
1718 },
1719 "order": null,
1720 "paid": true,
1721 "receipt_email": null,
1722 "receipt_number": null,
1723 "refunded": false,
1724 "refunds": {
1725 "object": "list",
1726 "data": [],
1727 "has_more": false,
1728 "total_count": 0,
1729 "url": "/v1/charges/ch_18zQ402eZvKYlo2CvQYLBOJ4/refunds"
1730 },
1731 "shipping": null,
1732 "source": {
1733 "id": "card_18oWmJ2eZvKYlo2CApIJRrtd",
1734 "object": "card",
1735 "address_city": null,
1736 "address_country": null,
1737 "address_line1": null,
1738 "address_line1_check": null,
1739 "address_line2": null,
1740 "address_state": null,
1741 "address_zip": null,
1742 "address_zip_check": null,
1743 "brand": "Visa",
1744 "country": "US",
1745 "customer": "cus_96kH68CmcC5XcM",
1746 "cvc_check": null,
1747 "dynamic_last4": null,
1748 "exp_month": 12,
1749 "exp_year": 2017,
1750 "funding": "credit",
1751 "last4": "4242",
1752 "metadata": {
1753 },
1754 "name": null,
1755 "tokenization_method": null
1756 },
1757 "source_transfer": null,
1758 "statement_descriptor": null,
1759 "status": "succeeded"
1760 }
1761 }
1762 }
1763}
1764```
1765
1766<a name="updateCharge"/>
1767## Stripe.updateCharge
1768Updates the specified charge by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
1769This request accepts only the `description`, `metadata`, `receipt_email`, `fraud_details`, and `shipping` as arguments.
1770
1771| Field | Type | Description
1772|-------------|------------|----------
1773| apiKey | credentials| The api key obtained from Stripe.
1774| chargeId | String | Id of a charge.
1775| description | String | 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.
1776| receiptEmail| String | The email address to send this charge's receipt to. The receipt will not be sent until the charge is paid. If this charge is for a customer, the email address specified here will override the customer's email address. Receipts will not be sent for test mode charges. If `receipt_email` is specified for a charge in live mode, a receipt will be sent regardless of your email settings.
1777| fraudDetails| JSON | A set of key/value pairs you can attach to a charge giving information about its riskiness. If you believe a charge is fraudulent, include a user_report key with a value of fraudulent. If you believe a charge is safe, include a user_report key with a value of safe. Note that you must refund a charge before setting the user_report to fraudulent. Stripe will use the information you send to improve our fraud detection algorithms.
1778| metadata | JSON | 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 null and then saving. To clear all keys, set metadata to null, then save.
1779| shipping | String | Shipping information for the charge. Helps prevent fraud on charges for physical goods.
1780
1781#### Request example
1782```json
1783{
1784 "apiKey": "...",
1785 "description": "Charge for andrew.martinez@example.com",
1786}
1787```
1788#### Response example
1789```json
1790{
1791 "callback":"success",
1792 "contextWrites":{
1793 "#":{
1794 "to":{
1795 "id": "ch_18zQ402eZvKYlo2CvQYLBOJ4",
1796 "object": "charge",
1797 "amount": 999,
1798 "amount_refunded": 0,
1799 "application_fee": null,
1800 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
1801 "captured": true,
1802 "created": 1475238268,
1803 "currency": "usd",
1804 "customer": "cus_96kH68CmcC5XcM",
1805 "description": "Charge for andrew.martinez@example.com",
1806 "destination": null,
1807 "dispute": null,
1808 "failure_code": null,
1809 "failure_message": null,
1810 "fraud_details": {
1811 },
1812 "invoice": "in_18zP7g2eZvKYlo2CUqGHFAlX",
1813 "livemode": false,
1814 "metadata": {
1815 },
1816 "order": null,
1817 "paid": true,
1818 "receipt_email": null,
1819 "receipt_number": null,
1820 "refunded": false,
1821 "refunds": {
1822 "object": "list",
1823 "data": [],
1824 "has_more": false,
1825 "total_count": 0,
1826 "url": "/v1/charges/ch_18zQ402eZvKYlo2CvQYLBOJ4/refunds"
1827 },
1828 "shipping": null,
1829 "source": {
1830 "id": "card_18oWmJ2eZvKYlo2CApIJRrtd",
1831 "object": "card",
1832 "address_city": null,
1833 "address_country": null,
1834 "address_line1": null,
1835 "address_line1_check": null,
1836 "address_line2": null,
1837 "address_state": null,
1838 "address_zip": null,
1839 "address_zip_check": null,
1840 "brand": "Visa",
1841 "country": "US",
1842 "customer": "cus_96kH68CmcC5XcM",
1843 "cvc_check": null,
1844 "dynamic_last4": null,
1845 "exp_month": 12,
1846 "exp_year": 2017,
1847 "funding": "credit",
1848 "last4": "4242",
1849 "metadata": {
1850 },
1851 "name": null,
1852 "tokenization_method": null
1853 },
1854 "source_transfer": null,
1855 "statement_descriptor": null,
1856 "status": "succeeded"
1857 }
1858 }
1859 }
1860}
1861```
1862
1863<a name="captureCharge"/>
1864## Stripe.captureCharge
1865Capture 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.
1866Uncaptured 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.
1867
1868| Field | Type | Description
1869|--------------------|------------|----------
1870| apiKey | credentials| The api key obtained from Stripe.
1871| chargeId | String | Id of a charge.
1872| amount | String | The amount to capture, which must be less than or equal to the original amount. Any additional amount will be automatically refunded.
1873| applicationFee | String | An application fee to add on to this charge. Can only be used with Stripe Connect.
1874| receiptEmail | credentials| The email address to send this charge’s receipt to. This will override the previously-specified email address for this charge, if one was set. Receipts will not be sent in test mode.
1875| statementDescriptor| credentials| An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you’re charging for is a race ticket, you may want to specify a statement_descriptor of RunClub 5K race ticket. The statement description may not include <> characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. Updating this value will overwrite the previous statement descriptor of this charge. While most banks display this information consistently, some may display it incorrectly or not at all
1876
1877#### Request example
1878```json
1879{
1880 "apiKey": "...",
1881 "chargeId": "sk_test_BQokikJOvBiI2HlWgH4olfQ2",
1882}
1883```
1884#### Response example
1885```json
1886{
1887 "callback":"success",
1888 "contextWrites":{
1889 "#":{
1890 "to": {
1891 "id": "ch_18zQ402eZvKYlo2CvQYLBOJ4",
1892 "object": "charge",
1893 "amount": 999,
1894 "amount_refunded": 0,
1895 "application_fee": null,
1896 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
1897 "captured": "true",
1898 "created": 1475238268,
1899 "currency": "usd",
1900 "customer": "cus_96kH68CmcC5XcM",
1901 "description": null,
1902 "destination": null,
1903 "dispute": null,
1904 "failure_code": null,
1905 "failure_message": null,
1906 "fraud_details": {
1907 },
1908 "invoice": "in_18zP7g2eZvKYlo2CUqGHFAlX",
1909 "livemode": false,
1910 "metadata": {
1911 },
1912 "order": null,
1913 "paid": true,
1914 "receipt_email": null,
1915 "receipt_number": null,
1916 "refunded": false,
1917 "refunds": {
1918 "object": "list",
1919 "data": [ ],
1920 "has_more": false,
1921 "total_count": 0,
1922 "url": "/v1/charges/ch_18zQ402eZvKYlo2CvQYLBOJ4/refunds"
1923 },
1924 "shipping": null,
1925 "source": {
1926 "id": "card_18oWmJ2eZvKYlo2CApIJRrtd",
1927 "object": "card",
1928 "address_city": null,
1929 "address_country": null,
1930 "address_line1": null,
1931 "address_line1_check": null,
1932 "address_line2": null,
1933 "address_state": null,
1934 "address_zip": null,
1935 "address_zip_check": null,
1936 "brand": "Visa",
1937 "country": "US",
1938 "customer": "cus_96kH68CmcC5XcM",
1939 "cvc_check": null,
1940 "dynamic_last4": null,
1941 "exp_month": 12,
1942 "exp_year": 2017,
1943 "funding": "credit",
1944 "last4": "4242",
1945 "metadata": {
1946 },
1947 "name": null,
1948 "tokenization_method": null
1949 },
1950 "source_transfer": null,
1951 "statement_descriptor": null,
1952 "status": "succeeded"
1953 }
1954 }
1955 }
1956}
1957```
1958
1959<a name="getChargesList"/>
1960## Stripe.getChargesList
1961Returns a list of charges you’ve previously created. The charges are returned in sorted order, with the most recent charges appearing first.
1962
1963| Field | Type | Description
1964|--------------|------------|----------
1965| apiKey | credentials| The api key obtained from Stripe.
1966| created | String | A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options: child arguments
1967| customer | String | Only return charges for the customer specified by this customer ID.
1968| endingBefore | String | 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.
1969| limit | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
1970| source | String | A filter on the list based on the source of the charge. The value can be a dictionary with the following options:
1971| startingAfter| String | 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.
1972
1973#### Request example
1974```json
1975{
1976 "apiKey": "...",
1977 "limit": 3,
1978}
1979```
1980#### Response example
1981```json
1982{
1983 "callback":"success",
1984 "contextWrites":{
1985 "#":{
1986 "to": {
1987 "object": "list",
1988 "url": "/v1/charges",
1989 "has_more": false,
1990 "data": [
1991 {
1992 "id": "ch_1904tu2eZvKYlo2C6CJe9Ina",
1993 "object": "charge",
1994 "amount": 999,
1995 "amount_refunded": 0,
1996 "application_fee": null,
1997 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
1998 "captured": true,
1999 "created": 1475395246,
2000 "currency": "usd",
2001 "customer": "cus_97QRFcUnI0a31P",
2002 "description": null,
2003 "destination": null,
2004 "dispute": null,
2005 "failure_code": null,
2006 "failure_message": null,
2007 "fraud_details": {
2008 },
2009 "invoice": "in_1903xi2eZvKYlo2CpcZ4ix6n",
2010 "livemode": false,
2011 "metadata": {
2012 },
2013 "order": null,
2014 "paid": true,
2015 "receipt_email": null,
2016 "receipt_number": null,
2017 "refunded": false,
2018 "refunds": {
2019 "object": "list",
2020 "data": [ ],
2021 "has_more": false,
2022 "total_count": 0,
2023 "url": "/v1/charges/ch_1904tu2eZvKYlo2C6CJe9Ina/refunds"
2024 },
2025 "shipping": null,
2026 "source": {
2027 "id": "card_18pBYv2eZvKYlo2CbcTNGZN4",
2028 "object": "card",
2029 "address_city": null,
2030 "address_country": null,
2031 "address_line1": null,
2032 "address_line1_check": null,
2033 "address_line2": null,
2034 "address_state": null,
2035 "address_zip": null,
2036 "address_zip_check": null,
2037 "brand": "Visa",
2038 "country": "US",
2039 "customer": "cus_97QRFcUnI0a31P",
2040 "cvc_check": null,
2041 "dynamic_last4": null,
2042 "exp_month": 12,
2043 "exp_year": 2017,
2044 "funding": "credit",
2045 "last4": "4242",
2046 "metadata": {
2047 },
2048 "name": null,
2049 "tokenization_method": null
2050 },
2051 "source_transfer": null,
2052 "statement_descriptor": null,
2053 "status": "succeeded"
2054 },
2055 {...},
2056 {...}
2057 ]
2058 }
2059 }
2060 }
2061}
2062```
2063
2064<a name="getCustomer"/>
2065## Stripe.getCustomer
2066Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.
2067
2068| Field | Type | Description
2069|-----------|------------|----------
2070| apiKey | credentials| The api key obtained from Stripe.
2071| customerId| String | The identifier of the customer to be retrieved.
2072
2073#### Request example
2074```json
2075{
2076 "apiKey": "...",
2077 "customerId": "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
2078}
2079```
2080#### Response example
2081```json
2082{
2083 "callback":"success",
2084 "contextWrites":{
2085 "#":{
2086 "to": {
2087 "id": "cus_9I04eaA61hXf5W",
2088 "object": "customer",
2089 "account_balance": 0,
2090 "created": 1475238307,
2091 "currency": "usd",
2092 "default_source": "card_18zQ422eZvKYlo2CIznAqoaV",
2093 "delinquent": false,
2094 "description": "Emily Martin",
2095 "discount": null,
2096 "email": "emily.martin.57@example.com",
2097 "livemode": false,
2098 "metadata": {
2099 },
2100 "shipping": null,
2101 "sources": {
2102 "object": "list",
2103 "data": [
2104 {
2105 "id": "card_18zQ422eZvKYlo2CIznAqoaV",
2106 "object": "card",
2107 "address_city": null,
2108 "address_country": null,
2109 "address_line1": null,
2110 "address_line1_check": null,
2111 "address_line2": null,
2112 "address_state": null,
2113 "address_zip": null,
2114 "address_zip_check": null,
2115 "brand": "Visa",
2116 "country": "US",
2117 "customer": "cus_9I04eaA61hXf5W",
2118 "cvc_check": "pass",
2119 "dynamic_last4": null,
2120 "exp_month": 12,
2121 "exp_year": 2017,
2122 "funding": "credit",
2123 "last4": "4242",
2124 "metadata": {
2125 },
2126 "name": null,
2127 "tokenization_method": null
2128 }
2129 ],
2130 "has_more": false,
2131 "total_count": 1,
2132 "url": "/v1/customers/cus_9I04eaA61hXf5W/sources"
2133 },
2134 "subscriptions": {
2135 "object": "list",
2136 "data": [ ],
2137 "has_more": false,
2138 "total_count": 0,
2139 "url": "/v1/customers/cus_9I04eaA61hXf5W/subscriptions"
2140 }
2141 }
2142 }
2143 }
2144}
2145```
2146
2147<a name="updateCustomer"/>
2148## Stripe.updateCustomer
2149Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the source parameter, that becomes the customer's active source (e.g., a card) to be used for all charges in the future. When you update a customer to a new valid source: for each of the customer's current subscriptions, if the subscription is in the past_due state, then the latest unpaid, unclosed invoice for the subscription will be retried (note that this retry will not count as an automatic retry, and will not affect the next regularly scheduled payment for the invoice). (Note also that no invoices pertaining to subscriptions in the unpaid state, or invoices pertaining to canceled subscriptions, will be retried as a result of updating the customer's source.)
2150This request accepts mostly the same arguments as the customer creation call.
2151
2152| Field | Type | Description
2153|---------------|------------|----------
2154| apiKey | credentials| The api key obtained from Stripe.
2155| customerId | String | If of customer to update.
2156| source | String | The source can either be a token, like the ones returned by our Stripe.js, or a dictionary containing a user’s credit card details (with the options shown below).child arguments
2157| accountBalance| String | 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.
2158| businessVatId | String | The customer’s VAT identification number. If you are using Relay, this field gets passed to tax provider you are using for your orders. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
2159| coupon | String | 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.
2160| description | String | 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 null and then saving.
2161| email | String | 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 null and then saving.
2162| metadata | JSON | 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 null and then saving.
2163| plan | String | The identifier of the plan to subscribe the customer to. If provided, the returned customer object will have a list of subscriptions that the customer is currently subscribed to. If you subscribe a customer to a plan without a free trial, the customer must have a valid card as well.
2164| taxPercent | String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice. Can only be used if a plan is provided.
2165| trialEnd | String | Unix timestamp representing the end of the trial period the customer will get before being charged. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer’s trial immediately. Only applies when the plan parameter is also provided.
2166
2167#### Request example
2168```json
2169{
2170 "apiKey": "...",
2171 "customerId": "cus_9I04eaA61hXf5W",
2172 "description": "Test",
2173}
2174```
2175#### Response example
2176```json
2177{
2178 "callback":"success",
2179 "contextWrites":{
2180 "#":{
2181 "to": {
2182 "id": "cus_9I04eaA61hXf5W",
2183 "object": "customer",
2184 "account_balance": 0,
2185 "created": 1475238307,
2186 "currency": "usd",
2187 "default_source": "card_18zQ422eZvKYlo2CIznAqoaV",
2188 "delinquent": false,
2189 "description": "Customer for andrew.martinez@example.com",
2190 "discount": null,
2191 "email": "emily.martin.57@example.com",
2192 "livemode": false,
2193 "metadata": {
2194 },
2195 "shipping": null,
2196 "sources": {
2197 "object": "list",
2198 "data": [
2199 {
2200 "id": "card_18zQ422eZvKYlo2CIznAqoaV",
2201 "object": "card",
2202 "address_city": null,
2203 "address_country": null,
2204 "address_line1": null,
2205 "address_line1_check": null,
2206 "address_line2": null,
2207 "address_state": null,
2208 "address_zip": null,
2209 "address_zip_check": null,
2210 "brand": "Visa",
2211 "country": "US",
2212 "customer": "cus_9I04eaA61hXf5W",
2213 "cvc_check": "pass",
2214 "dynamic_last4": null,
2215 "exp_month": 12,
2216 "exp_year": 2017,
2217 "funding": "credit",
2218 "last4": "4242",
2219 "metadata": {
2220 },
2221 "name": null,
2222 "tokenization_method": null
2223 }
2224 ],
2225 "has_more": false,
2226 "total_count": 1,
2227 "url": "/v1/customers/cus_9I04eaA61hXf5W/sources"
2228 },
2229 "subscriptions": {
2230 "object": "list",
2231 "data": [],
2232 "has_more": false,
2233 "total_count": 0,
2234 "url": "/v1/customers/cus_9I04eaA61hXf5W/subscriptions"
2235 }
2236 }
2237 }
2238 }
2239}
2240```
2241
2242<a name="deleteCustomer"/>
2243## Stripe.deleteCustomer
2244Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.
2245
2246| Field | Type | Description
2247|-----------|------------|----------
2248| apiKey | credentials| The api key obtained from Stripe.
2249| customerId| String | If of customer to update.
2250
2251#### Request example
2252```json
2253{
2254 "apiKey": "...",
2255 "customerId": "cus_9I04eaA61hXf5W"
2256}
2257```
2258#### Response example
2259```json
2260{
2261 "callback":"success",
2262 "contextWrites":{
2263 "#":{
2264 "to": {
2265 "deleted": true,
2266 "id": "cus_9I04eaA61hXf5W"
2267 }
2268 }
2269 }
2270}
2271```
2272
2273<a name="getCustomerList"/>
2274## Stripe.getCustomerList
2275Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.
2276
2277| Field | Type | Description
2278|-------|------------|----------
2279| apiKey| credentials| The api key obtained from Stripe.
2280
2281#### Request example
2282```json
2283{
2284 "apiKey": "..."
2285}
2286```
2287#### Response example
2288```json
2289{
2290 "callback":"success",
2291 "contextWrites":{
2292 "#":{
2293 "to":{
2294 "object": "list",
2295 "url": "/v1/customers",
2296 "has_more": false,
2297 "data": [
2298 {
2299 "id": "cus_9I04eaA61hXf5W",
2300 "object": "customer",
2301 "account_balance": 0,
2302 "created": 1475238307,
2303 "currency": "usd",
2304 "default_source": "card_18zQ422eZvKYlo2CIznAqoaV",
2305 "delinquent": false,
2306 "description": "Emily Martin",
2307 "discount": null,
2308 "email": "emily.martin.57@example.com",
2309 "livemode": false,
2310 "metadata": {
2311 },
2312 "shipping": null,
2313 "sources": {
2314 "object": "list",
2315 "data": [
2316 {
2317 "id": "card_18zQ422eZvKYlo2CIznAqoaV",
2318 "object": "card",
2319 "address_city": null,
2320 "address_country": null,
2321 "address_line1": null,
2322 "address_line1_check": null,
2323 "address_line2": null,
2324 "address_state": null,
2325 "address_zip": null,
2326 "address_zip_check": null,
2327 "brand": "Visa",
2328 "country": "US",
2329 "customer": "cus_9I04eaA61hXf5W",
2330 "cvc_check": "pass",
2331 "dynamic_last4": null,
2332 "exp_month": 12,
2333 "exp_year": 2017,
2334 "funding": "credit",
2335 "last4": "4242",
2336 "metadata": {
2337 },
2338 "name": null,
2339 "tokenization_method": null
2340 }
2341 ],
2342 "has_more": false,
2343 "total_count": 1,
2344 "url": "/v1/customers/cus_9I04eaA61hXf5W/sources"
2345 },
2346 "subscriptions": {
2347 "object": "list",
2348 "data": [],
2349 "has_more": false,
2350 "total_count": 0,
2351 "url": "/v1/customers/cus_9I04eaA61hXf5W/subscriptions"
2352 }
2353 },
2354 {...},
2355 {...}
2356 ]
2357 }
2358 }
2359 }
2360}
2361```
2362
2363<a name="getDispute"/>
2364## Stripe.getDispute
2365Retrieves the dispute with the given ID.
2366
2367| Field | Type | Description
2368|----------|------------|----------
2369| apiKey | credentials| The api key obtained from Stripe.
2370| disputeId| String | ID of dispute to retrieve.
2371
2372#### Request example
2373```json
2374{
2375 "apiKey": "...",
2376 "disputeId": "dp_17Vv962eZvKYlo2CU7XhGGzB"
2377}
2378```
2379#### Response example
2380```json
2381{
2382 "callback":"success",
2383 "contextWrites":{
2384 "#":{
2385 "to":{
2386 "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
2387 "object": "dispute",
2388 "amount": 100,
2389 "balance_transactions": [
2390 {
2391 "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
2392 "object": "balance_transaction",
2393 "amount": -100,
2394 "available_on": 1454025600,
2395 "created": 1453431572,
2396 "currency": "usd",
2397 "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
2398 "fee": 1500,
2399 "fee_details": [
2400 {
2401 "amount": 1500,
2402 "application": null,
2403 "currency": "usd",
2404 "description": "Dispute fee",
2405 "type": "stripe_fee"
2406 }
2407 ],
2408 "net": -1600,
2409 "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
2410 "sourced_transfers": {
2411 "object": "list",
2412 "data": [],
2413 "has_more": false,
2414 "total_count": 0,
2415 "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
2416 },
2417 "status": "available",
2418 "type": "adjustment"
2419 }
2420 ],
2421 "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
2422 "created": 1453431572,
2423 "currency": "usd",
2424 "evidence": {
2425 "access_activity_log": null,
2426 "billing_address": null,
2427 "cancellation_policy": null,
2428 "cancellation_policy_disclosure": null,
2429 "cancellation_rebuttal": null,
2430 "customer_communication": null,
2431 "customer_email_address": null,
2432 "customer_name": null,
2433 "customer_purchase_ip": null,
2434 "customer_signature": null,
2435 "duplicate_charge_documentation": null,
2436 "duplicate_charge_explanation": null,
2437 "duplicate_charge_id": null,
2438 "product_description": null,
2439 "receipt": null,
2440 "refund_policy": null,
2441 "refund_policy_disclosure": null,
2442 "refund_refusal_explanation": null,
2443 "service_date": null,
2444 "service_documentation": null,
2445 "shipping_address": null,
2446 "shipping_carrier": null,
2447 "shipping_date": null,
2448 "shipping_documentation": null,
2449 "shipping_tracking_number": null,
2450 "uncategorized_file": null,
2451 "uncategorized_text": null
2452 },
2453 "evidence_details": {
2454 "due_by": 1454889599,
2455 "has_evidence": false,
2456 "past_due": false,
2457 "submission_count": 0
2458 },
2459 "is_charge_refundable": false,
2460 "livemode": false,
2461 "metadata": {
2462 },
2463 "reason": "general",
2464 "status": "lost"
2465 }
2466 }
2467 }
2468}
2469```
2470
2471<a name="updateDispute"/>
2472## Stripe.updateDispute
2473When you get a dispute, contacting your customer is always the best first step. If that doesn’t work, you can submit evidence in order to help us resolve the dispute in your favor. You can do this in your dashboard, but if you prefer, you can use the API to submit evidence programmatically.
2474
2475| Field | Type | Description
2476|----------|------------|----------
2477| apiKey | credentials| The api key obtained from Stripe.
2478| disputeId| String | ID of dispute to retrieve.
2479| evidence | JSON | Evidence to upload to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review.
2480| metadata | JSON | A set of key/value pairs that you can attach to a dispute object. It can be useful for storing additional information about the dispute in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
2481
2482#### Request example
2483```json
2484{
2485 "apiKey": "...",
2486 "disputeId": "dp_17Vv962eZvKYlo2CU7XhGGzB",
2487 "evidence": "{
2488 \"customer_name\": "Sophia Moore",
2489 \"product_description\": \"Comfortable cotton t-shirt\",
2490 \"shipping_documentation\": \"file_18wzPK2eZvKYlo2CKdXyu53D\"
2491 }",
2492 "metadata": "..."
2493}
2494```
2495#### Response example
2496```json
2497{
2498 "callback":"success",
2499 "contextWrites":{
2500 "#":{
2501 "to":{
2502 "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
2503 "object": "dispute",
2504 "amount": 100,
2505 "balance_transactions": [
2506 {
2507 "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
2508 "object": "balance_transaction",
2509 "amount": -100,
2510 "available_on": 1454025600,
2511 "created": 1453431572,
2512 "currency": "usd",
2513 "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
2514 "fee": 1500,
2515 "fee_details": [
2516 {
2517 "amount": 1500,
2518 "application": null,
2519 "currency": "usd",
2520 "description": "Dispute fee",
2521 "type": "stripe_fee"
2522 }
2523 ],
2524 "net": -1600,
2525 "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
2526 "sourced_transfers": {
2527 "object": "list",
2528 "data": [],
2529 "has_more": false,
2530 "total_count": 0,
2531 "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
2532 },
2533 "status": "available",
2534 "type": "adjustment"
2535 }
2536 ],
2537 "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
2538 "created": 1453431572,
2539 "currency": "usd",
2540 "evidence": {
2541 "product_description": "Comfortable cotton t-shirt",
2542 "customer_name": "Sophia Moore",
2543 "customer_email_address": null,
2544 "billing_address": null,
2545 "customer_purchase_ip": null,
2546 "shipping_address": null,
2547 "shipping_date": null,
2548 "shipping_carrier": null,
2549 "shipping_tracking_number": null,
2550 "service_date": null,
2551 "access_activity_log": null,
2552 "duplicate_charge_id": null,
2553 "duplicate_charge_explanation": null,
2554 "refund_policy_disclosure": null,
2555 "refund_refusal_explanation": null,
2556 "cancellation_policy_disclosure": null,
2557 "cancellation_rebuttal": null,
2558 "uncategorized_text": null,
2559 "customer_signature": null,
2560 "receipt": null,
2561 "shipping_documentation": "file_18wzPK2eZvKYlo2CKdXyu53D",
2562 "service_documentation": null,
2563 "duplicate_charge_documentation": null,
2564 "refund_policy": null,
2565 "cancellation_policy": null,
2566 "customer_communication": null,
2567 "uncategorized_file": null
2568 },
2569 "evidence_details": {
2570 "due_by": 1454889599,
2571 "has_evidence": false,
2572 "past_due": false,
2573 "submission_count": 0
2574 },
2575 "is_charge_refundable": false,
2576 "livemode": false,
2577 "metadata": {
2578 },
2579 "reason": "general",
2580 "status": "lost"
2581 }
2582 }
2583 }
2584}
2585```
2586
2587<a name="closeDispute"/>
2588## Stripe.closeDispute
2589Closing 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
2590The status of the dispute will change from needs_response to lost. Closing a dispute is irreversible.
2591
2592| Field | Type | Description
2593|----------|------------|----------
2594| apiKey | credentials| The api key obtained from Stripe.
2595| disputeId| String | ID of dispute to retrieve.
2596
2597#### Request example
2598```json
2599{
2600 "apiKey": "...",
2601 "disputeId": "dp_17Vv962eZvKYlo2CU7XhGGzB"
2602}
2603```
2604#### Response example
2605```json
2606{
2607 "callback":"success",
2608 "contextWrites":{
2609 "#":{
2610 "to": {
2611 "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
2612 "object": "dispute",
2613 "amount": 100,
2614 "balance_transactions": [
2615 {
2616 "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
2617 "object": "balance_transaction",
2618 "amount": -100,
2619 "available_on": 1454025600,
2620 "created": 1453431572,
2621 "currency": "usd",
2622 "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
2623 "fee": 1500,
2624 "fee_details": [
2625 {
2626 "amount": 1500,
2627 "application": null,
2628 "currency": "usd",
2629 "description": "Dispute fee",
2630 "type": "stripe_fee"
2631 }
2632 ],
2633 "net": -1600,
2634 "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
2635 "sourced_transfers": {
2636 "object": "list",
2637 "data": [ ],
2638 "has_more": false,
2639 "total_count": 0,
2640 "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
2641 },
2642 "status": "available",
2643 "type": "adjustment"
2644 }
2645 ],
2646 "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
2647 "created": 1453431572,
2648 "currency": "usd",
2649 "evidence": {
2650 "access_activity_log": null,
2651 "billing_address": null,
2652 "cancellation_policy": null,
2653 "cancellation_policy_disclosure": null,
2654 "cancellation_rebuttal": null,
2655 "customer_communication": null,
2656 "customer_email_address": null,
2657 "customer_name": null,
2658 "customer_purchase_ip": null,
2659 "customer_signature": null,
2660 "duplicate_charge_documentation": null,
2661 "duplicate_charge_explanation": null,
2662 "duplicate_charge_id": null,
2663 "product_description": null,
2664 "receipt": null,
2665 "refund_policy": null,
2666 "refund_policy_disclosure": null,
2667 "refund_refusal_explanation": null,
2668 "service_date": null,
2669 "service_documentation": null,
2670 "shipping_address": null,
2671 "shipping_carrier": null,
2672 "shipping_date": null,
2673 "shipping_documentation": null,
2674 "shipping_tracking_number": null,
2675 "uncategorized_file": null,
2676 "uncategorized_text": null
2677 },
2678 "evidence_details": {
2679 "due_by": 1454889599,
2680 "has_evidence": false,
2681 "past_due": false,
2682 "submission_count": 0
2683 },
2684 "is_charge_refundable": false,
2685 "livemode": false,
2686 "metadata": {
2687 },
2688 "reason": "general",
2689 "status": "lost"
2690 }
2691 }
2692 }
2693}
2694```
2695
2696<a name="getDisputes"/>
2697## Stripe.getDisputes
2698Returns a list of your disputes.
2699
2700| Field | Type | Description
2701|-------|------------|----------
2702| apiKey| credentials| The api key obtained from Stripe.
2703
2704#### Request example
2705```json
2706{ "apiKey": "..."
2707}
2708```
2709#### Response example
2710```json
2711{
2712 "callback":"success",
2713 "contextWrites":{
2714 "#":{
2715 "to": {
2716 "object": "list",
2717 "url": "/v1/disputes",
2718 "has_more": false,
2719 "data": [
2720 {
2721 "id": "dp_17Vv962eZvKYlo2CU7XhGGzB",
2722 "object": "dispute",
2723 "amount": 100,
2724 "balance_transactions": [
2725 {
2726 "id": "txn_17Vv962eZvKYlo2ChC4UKwX7",
2727 "object": "balance_transaction",
2728 "amount": -100,
2729 "available_on": 1454025600,
2730 "created": 1453431572,
2731 "currency": "usd",
2732 "description": "Chargeback withdrawal for ch_17Vv952eZvKYlo2ChNXOPPWS",
2733 "fee": 1500,
2734 "fee_details": [
2735 {
2736 "amount": 1500,
2737 "application": null,
2738 "currency": "usd",
2739 "description": "Dispute fee",
2740 "type": "stripe_fee"
2741 }
2742 ],
2743 "net": -1600,
2744 "source": "dp_17Vv962eZvKYlo2CU7XhGGzB",
2745 "sourced_transfers": {
2746 "object": "list",
2747 "data": [],
2748 "has_more": false,
2749 "total_count": 0,
2750 "url": "/v1/transfers?source_transaction=ad_17Vv962eZvKYlo2CHxgHaG1p"
2751 },
2752 "status": "available",
2753 "type": "adjustment"
2754 }
2755 ],
2756 "charge": "ch_17Vv952eZvKYlo2ChNXOPPWS",
2757 "created": 1453431572,
2758 "currency": "usd",
2759 "evidence": {
2760 "access_activity_log": null,
2761 "billing_address": null,
2762 "cancellation_policy": null,
2763 "cancellation_policy_disclosure": null,
2764 "cancellation_rebuttal": null,
2765 "customer_communication": null,
2766 "customer_email_address": null,
2767 "customer_name": null,
2768 "customer_purchase_ip": null,
2769 "customer_signature": null,
2770 "duplicate_charge_documentation": null,
2771 "duplicate_charge_explanation": null,
2772 "duplicate_charge_id": null,
2773 "product_description": null,
2774 "receipt": null,
2775 "refund_policy": null,
2776 "refund_policy_disclosure": null,
2777 "refund_refusal_explanation": null,
2778 "service_date": null,
2779 "service_documentation": null,
2780 "shipping_address": null,
2781 "shipping_carrier": null,
2782 "shipping_date": null,
2783 "shipping_documentation": null,
2784 "shipping_tracking_number": null,
2785 "uncategorized_file": null,
2786 "uncategorized_text": null
2787 },
2788 "evidence_details": {
2789 "due_by": 1454889599,
2790 "has_evidence": false,
2791 "past_due": false,
2792 "submission_count": 0
2793 },
2794 "is_charge_refundable": false,
2795 "livemode": false,
2796 "metadata": {
2797 },
2798 "reason": "general",
2799 "status": "lost"
2800 },
2801 {...},
2802 {...}
2803 ]
2804 }
2805 }
2806 }
2807}
2808```
2809
2810<a name="getEvent"/>
2811## Stripe.getEvent
2812Retrieves the details of an event. Supply the unique identifier of the event, which you might have received in a webhook.
2813
2814| Field | Type | Description
2815|--------|------------|----------
2816| apiKey | credentials| The api key obtained from Stripe.
2817| eventId| credentials| The api key obtained from Stripe.
2818
2819#### Request example
2820```json
2821{
2822 "apiKey": "...",
2823 "eventId": "evt_18zQ4e2eZvKYlo2Cd9eGkwal"
2824}
2825```
2826#### Response example
2827```json
2828{
2829 "callback":"success",
2830 "contextWrites":{
2831 "#":{
2832 "to": {
2833 "id": "evt_18zQ4e2eZvKYlo2Cd9eGkwal",
2834 "object": "event",
2835 "api_version": "2016-07-06",
2836 "created": 1475238308,
2837 "data": {
2838 "object": {
2839 "id": "card_18zQ422eZvKYlo2CIznAqoaV",
2840 "object": "card",
2841 "address_city": null,
2842 "address_country": null,
2843 "address_line1": null,
2844 "address_line1_check": null,
2845 "address_line2": null,
2846 "address_state": null,
2847 "address_zip": null,
2848 "address_zip_check": null,
2849 "brand": "Visa",
2850 "country": "US",
2851 "customer": "cus_9I04eaA61hXf5W",
2852 "cvc_check": "pass",
2853 "dynamic_last4": null,
2854 "exp_month": 12,
2855 "exp_year": 2017,
2856 "fingerprint": "Xt5EWLLDS7FJjR1c",
2857 "funding": "credit",
2858 "last4": "4242",
2859 "metadata": {
2860 },
2861 "name": null,
2862 "tokenization_method": null
2863 }
2864 },
2865 "livemode": false,
2866 "pending_webhooks": 0,
2867 "request": "req_9I04Pra7tfXffn",
2868 "type": "customer.source.created"
2869 }
2870 }
2871 }
2872}
2873```
2874
2875<a name="getEventList"/>
2876## Stripe.getEventList
2877List events, going back up to 30 days.
2878
2879| Field | Type | Description
2880|-------|------------|----------
2881| apiKey| credentials| The api key obtained from Stripe.
2882| type | String | A string containing a specific event name, or group of events using * as a wildcard. The list will be filtered to include only events with a matching event property.
2883
2884#### Request example
2885```json
2886{
2887 "apiKey": "...",
2888}
2889```
2890#### Response example
2891```json
2892{
2893 "callback":"success",
2894 "contextWrites":{
2895 "#":{
2896 "to": {
2897 "object": "list",
2898 "url": "/v1/events",
2899 "has_more": false,
2900 "data": [
2901 {
2902 "id": "evt_18zQ4e2eZvKYlo2Cd9eGkwal",
2903 "object": "event",
2904 "api_version": "2016-07-06",
2905 "created": 1475238308,
2906 "data": {
2907 "object": {
2908 "id": "card_18zQ422eZvKYlo2CIznAqoaV",
2909 "object": "card",
2910 "address_city": null,
2911 "address_country": null,
2912 "address_line1": null,
2913 "address_line1_check": null,
2914 "address_line2": null,
2915 "address_state": null,
2916 "address_zip": null,
2917 "address_zip_check": null,
2918 "brand": "Visa",
2919 "country": "US",
2920 "customer": "cus_9I04eaA61hXf5W",
2921 "cvc_check": "pass",
2922 "dynamic_last4": null,
2923 "exp_month": 12,
2924 "exp_year": 2017,
2925 "fingerprint": "Xt5EWLLDS7FJjR1c",
2926 "funding": "credit",
2927 "last4": "4242",
2928 "metadata": {
2929 },
2930 "name": null,
2931 "tokenization_method": null
2932 }
2933 },
2934 "livemode": false,
2935 "pending_webhooks": 0,
2936 "request": "req_9I04Pra7tfXffn",
2937 "type": "customer.source.created"
2938 },
2939 {...},
2940 {...}
2941 ]
2942 }
2943 }
2944 }
2945}
2946```
2947
2948<a name="createFileUpload"/>
2949## Stripe.createFileUpload
2950To upload a file to Stripe, you’ll need to send a request of type multipart/form-data. The request should contain the file you would like to upload, as well as the parameters for creating a file.
2951
2952| Field | Type | Description
2953|--------|------------|----------
2954| apiKey | credentials| The api key obtained from Stripe.
2955| file | String | A file to upload.
2956| purpose| String | The purpoe of the uploaded file. Possible values are `business_logo`, `dispute_evidence`, `identity_document`, `incorporation_article`, `incorporation_document`, `payment_provider_transfer`, `product_feed`.
2957
2958#### Request example
2959```json
2960{
2961 "apiKey": "...",
2962 "file": "...",
2963 "purpose": "..."
2964}
2965```
2966#### Response example
2967```json
2968{
2969 "callback":"success",
2970 "contextWrites":{
2971 "#":{
2972 "to": {
2973 "id": "file_18wzPK2eZvKYlo2CKdXyu53D",
2974 "object": "file_upload",
2975 "created": 1474659146,
2976 "purpose": "identity_document",
2977 "size": 76545,
2978 "type": "jpg"
2979 }
2980 }
2981 }
2982}
2983```
2984
2985<a name="createRefund"/>
2986## Stripe.createRefund
2987When you create a new refund, you must specify a charge to create it on.
2988Creating a new refund will refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged. The fees you were originally charged are also refunded.
2989You 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.
2990Once entirely refunded, a charge can't be refunded again. This method will throw an error when called on an already-refunded charge, or when trying to refund more money than is left on a charge.
2991
2992| Field | Type | Description
2993|---------------------|------------|----------
2994| apiKey | credentials| The api key obtained from Stripe.
2995| chargeId | String | The identifier of the charge to refund.
2996| amount | String | 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.
2997| metadata | JSON | A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
2998| reason | String | String indicating the reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer. Specifying fraudulent as the reason when you believe the charge to be fraudulent will help us improve our fraud detection algorithms.
2999| refundApplicationFee| String | 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.
3000| reverseTransfer | String | Boolean indicating whether the transfer should be reversed when refunding this charge. The transfer will be reversed for the same amount being refunded (either the entire or partial amount). A transfer can only be reversed by the application that created the charge.
3001
3002#### Request example
3003```json
3004{
3005 "apiKey": "...",
3006 "chargeId": "ch_18zQ402eZvKYlo2CvQYLBOJ4",
3007}
3008```
3009#### Response example
3010```json
3011{
3012 "callback":"success",
3013 "contextWrites":{
3014 "#":{
3015 "to": {
3016 "id": "re_18zP2v2eZvKYlo2Ct9PUKMPw",
3017 "object": "refund",
3018 "amount": 300,
3019 "balance_transaction": "txn_18zP2v2eZvKYlo2C5HkvErZJ",
3020 "charge": "ch_18zNpY2eZvKYlo2Cm37H95Sz",
3021 "created": 1475234357,
3022 "currency": "usd",
3023 "metadata": {
3024 },
3025 "reason": null,
3026 "receipt_number": null,
3027 "status": "succeeded"
3028 }
3029 }
3030 }
3031}
3032```
3033
3034<a name="getRefund"/>
3035## Stripe.getRefund
3036Retrieves the details of an existing refund.
3037
3038| Field | Type | Description
3039|---------|------------|----------
3040| apiKey | credentials| The api key obtained from Stripe.
3041| refundId| String | ID of refund to retrieve.
3042
3043#### Request example
3044```json
3045{
3046 "apiKey": "...",
3047 "refundId": "re_18zP2v2eZvKYlo2Ct9PUKMPw"
3048}
3049```
3050#### Response example
3051```json
3052{
3053 "callback":"success",
3054 "contextWrites":{
3055 "#":{
3056 "to": {
3057 "id": "re_18zP2v2eZvKYlo2Ct9PUKMPw",
3058 "object": "refund",
3059 "amount": 300,
3060 "balance_transaction": "txn_18zP2v2eZvKYlo2C5HkvErZJ",
3061 "charge": "ch_18zNpY2eZvKYlo2Cm37H95Sz",
3062 "created": 1475234357,
3063 "currency": "usd",
3064 "metadata": {
3065 },
3066 "reason": null,
3067 "receipt_number": null,
3068 "status": "succeeded"
3069 }
3070 }
3071 }
3072}
3073```
3074
3075<a name="updateRefund"/>
3076## Stripe.updateRefund
3077Updates the specified refund by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
3078This request only accepts metadata as an argument.
3079
3080| Field | Type | Description
3081|---------|------------|----------
3082| apiKey | credentials| The api key obtained from Stripe.
3083| refundId| String | ID of refund to retrieve.
3084| metadata| JSON | A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
3085
3086#### Request example
3087```json
3088{
3089 "apiKey": "...",
3090 "refundId": "re_18zP2v2eZvKYlo2Ct9PUKMPw",
3091 "metadata": "..."
3092}
3093```
3094#### Response example
3095```json
3096{
3097 "callback":"success",
3098 "contextWrites":{
3099 "#":{
3100 "to": {
3101 "id": "re_18zP2v2eZvKYlo2Ct9PUKMPw",
3102 "object": "refund",
3103 "amount": 300,
3104 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
3105 "charge": "ch_18zNpY2eZvKYlo2Cm37H95Sz",
3106 "created": 1475234357,
3107 "currency": "usd",
3108 "metadata": {
3109 "key": "value"
3110 },
3111 "reason": null,
3112 "receipt_number": null,
3113 "status": "succeeded"
3114 }
3115 }
3116 }
3117}
3118```
3119
3120<a name="getRefundList"/>
3121## Stripe.getRefundList
3122Returns a list of all refunds you’ve previously created. The refunds are returned in sorted order, with the most recent refunds appearing first. For convenience, the 10 most recent refunds are always available by default on the charge object.
3123
3124| Field | Type | Description
3125|-------|------------|----------
3126| apiKey| credentials| The api key obtained from Stripe.
3127
3128#### Request example
3129```json
3130{ "apiKey": "..."
3131}
3132```
3133#### Response example
3134```json
3135{
3136 "callback":"success",
3137 "contextWrites":{
3138 "#":{
3139 "to": {
3140 "object": "list",
3141 "url": "/v1/refunds",
3142 "has_more": false,
3143 "data": [
3144 {
3145 "id": "re_18zP2v2eZvKYlo2Ct9PUKMPw",
3146 "object": "refund",
3147 "amount": 300,
3148 "balance_transaction": "txn_18zP2v2eZvKYlo2C5HkvErZJ",
3149 "charge": "ch_18zNpY2eZvKYlo2Cm37H95Sz",
3150 "created": 1475234357,
3151 "currency": "usd",
3152 "metadata": {
3153 },
3154 "reason": null,
3155 "receipt_number": null,
3156 "status": "succeeded"
3157 },
3158 {...},
3159 {...}
3160 ]
3161 }
3162 }
3163 }
3164}
3165```
3166
3167<a name="createCardToken"/>
3168## Stripe.createCardToken
3169Creates a single use token that wraps the details of a credit card. This token can be used in place of a credit card object with any API method. These tokens can only be used once: by creating a new charge object, or attaching them to a customer.
3170
3171| Field | Type | Description
3172|--------------------|------------|----------
3173| apiKey | credentials| The api key obtained from Stripe.
3174| cardNumber | String | Number of card
3175| cardExpirationMonth| Number | Expiration month of card
3176| cardExpirationYear | Number | Expiration year of card
3177| cardCvc | String | CVC code of card
3178
3179#### Request example
3180```json
3181{
3182 "apiKey": "...",
3183 "cardNumber": "4242424242424242",
3184 "cardExpirationMonth": 12,
3185 "cardExpirationYear": 2017,
3186 "cardCvc": "123"
3187}
3188```
3189#### Response example
3190```json
3191{
3192 "callback":"success",
3193 "contextWrites":{
3194 "#":{
3195 "to": {
3196 "id": "tok_189fTS2eZvKYlo2CcYJIOGkr",
3197 "object": "token",
3198 "card": {
3199 "id": "card_189fTR2eZvKYlo2CnJ7asfrs",
3200 "object": "card",
3201 "address_city": null,
3202 "address_country": null,
3203 "address_line1": null,
3204 "address_line1_check": null,
3205 "address_line2": null,
3206 "address_state": null,
3207 "address_zip": null,
3208 "address_zip_check": null,
3209 "brand": "Visa",
3210 "country": "US",
3211 "cvc_check": null,
3212 "dynamic_last4": null,
3213 "exp_month": 8,
3214 "exp_year": 2017,
3215 "funding": "credit",
3216 "last4": "4242",
3217 "metadata": {
3218 },
3219 "name": null,
3220 "tokenization_method": null
3221 },
3222 "client_ip": null,
3223 "created": 1462904450,
3224 "livemode": false,
3225 "type": "card",
3226 "used": false
3227 }
3228 }
3229 }
3230}
3231```
3232
3233<a name="createBankAccountToken"/>
3234## Stripe.createBankAccountToken
3235Creates a single use token that wraps the details of a bank account. This token can be used in place of a bank account object with any API method. These tokens can only be used once: by attaching them to a recipient or managed account.
3236
3237| Field | Type | Description
3238|-----------------------------|------------|----------
3239| apiKey | credentials| The api key obtained from Stripe.
3240| bankAccountCountry | String | The bank account country
3241| bankAccountCurrency | String | The bank account currency
3242| bankAccountAccountHolderName| String | The bank account holder name
3243| bankAccountAccountHolderType| String | The bank account holder type
3244| bankAccountRoutingNumber | String | The bank account routing number
3245| bankAccountNumber | String | The bank account number
3246
3247#### Request example
3248```json
3249{
3250 "apiKey": "...",
3251 "bankAccountCountry": "US",
3252 "bankAccountCurrency": "usd",
3253 "bankAccountAccountHolderName": "Anthony Anderson",
3254 "bankAccountAccountHolderType": "individual",
3255 "bankAccountRoutingNumber": "110000000",
3256 "bankAccountNumber": "000123456789"
3257}
3258```
3259#### Response example
3260```json
3261{
3262 "callback":"success",
3263 "contextWrites":{
3264 "#":{
3265 "to":{
3266 "id": "btok_9I05hAdQf5iXZ8",
3267 "object": "token",
3268 "bank_account": {
3269 "id": "ba_18zQ5k2eZvKYlo2C5dxFlaCC",
3270 "object": "bank_account",
3271 "account_holder_name": "Jane Austen",
3272 "account_holder_type": "individual",
3273 "bank_name": "STRIPE TEST BANK",
3274 "country": "US",
3275 "currency": "usd",
3276 "fingerprint": "1JWtPxqbdX5Gamtc",
3277 "last4": "6789",
3278 "routing_number": "110000000",
3279 "status": "new"
3280 },
3281 "client_ip": null,
3282 "created": 1475238376,
3283 "livemode": false,
3284 "type": "bank_account",
3285 "used": false
3286 }
3287 }
3288 }
3289}
3290```
3291
3292<a name="createPiiToken"/>
3293## Stripe.createPiiToken
3294Creates a single use token that wraps the details of personally identifiable information (PII). This token can be used in place of a personal_id_number in the Account Update API method. These tokens can only be used once.
3295
3296| Field | Type | Description
3297|-----------------|------------|----------
3298| apiKey | credentials| The api key obtained from Stripe.
3299| personalIdNumber| String | The bank account country
3300
3301#### Request example
3302```json
3303{
3304 "apiKey": "...",
3305 "personalIdNumber": "000000000"
3306}
3307```
3308#### Response example
3309```json
3310{
3311 "callback":"success",
3312 "contextWrites":{
3313 "#":{
3314 "to": {
3315 "id": "pii_17RAJV2eZvKYlo2CDyqjNWJ4",
3316 "object": "token",
3317 "client_ip": "8.21.168.72",
3318 "created": 1452298237,
3319 "livemode": false,
3320 "type": "pii",
3321 "used": false
3322 }
3323 }
3324 }
3325}
3326```
3327
3328<a name="getToken"/>
3329## Stripe.getToken
3330Retrieves the token with the given ID.
3331
3332| Field | Type | Description
3333|--------|------------|----------
3334| apiKey | credentials| The api key obtained from Stripe.
3335| tokenId| String | The ID of the desired token.
3336
3337#### Request example
3338```json
3339{
3340 "apiKey": "...",
3341 "tokenId": "tok_189fTS2eZvKYlo2CcYJIOGkr"
3342}
3343```
3344#### Response example
3345```json
3346{
3347 "callback":"success",
3348 "contextWrites":{
3349 "#":{
3350 "to": {
3351 "id": "tok_189fTS2eZvKYlo2CcYJIOGkr",
3352 "object": "token",
3353 "card": {
3354 "id": "card_189fTR2eZvKYlo2CnJ7asfrs",
3355 "object": "card",
3356 "address_city": null,
3357 "address_country": null,
3358 "address_line1": null,
3359 "address_line1_check": null,
3360 "address_line2": null,
3361 "address_state": null,
3362 "address_zip": null,
3363 "address_zip_check": null,
3364 "brand": "Visa",
3365 "country": "US",
3366 "cvc_check": null,
3367 "dynamic_last4": null,
3368 "exp_month": 8,
3369 "exp_year": 2017,
3370 "funding": "credit",
3371 "last4": "4242",
3372 "metadata": {
3373 },
3374 "name": null,
3375 "tokenization_method": null
3376 },
3377 "client_ip": null,
3378 "created": 1462904450,
3379 "livemode": false,
3380 "type": "card",
3381 "used": false
3382 }
3383 }
3384 }
3385}
3386```
3387
3388<a name="createTransfer"/>
3389## Stripe.createTransfer
3390To send funds from your Stripe account to a third-party recipient or to your own bank account, you create a new transfer object. Your Stripe balance must be able to cover the transfer amount, or you'll receive an "Insufficient Funds" error.
3391If your API key is in test mode, money won't actually be sent, though everything else will occur as if in live mode.
3392If you are creating a manual transfer or a special case transfer on a Stripe account that uses multiple payment source types, you'll need to specify the source type balance that the transfer should draw from. The balance object details available and pending amounts by source type.
3393
3394| Field | Type | Description
3395|--------------------|------------|----------
3396| apiKey | credentials| The api key obtained from Stripe.
3397| amount | Number | A positive integer in cents representing how much to transfer.
3398| currency | String | 3-letter ISO code for currency
3399| destination | String | The id of a bank account or a card to send the transfer to, or the string `default_for_currency` to use the default external account for the specified currency.
3400| description | String | An arbitrary string which you can attach to a transfer object. It is displayed when in the web interface alongside the transfer.
3401| sourceTransaction | String | You can use this parameter to transfer funds from a charge (or other transaction) before they are added to your available balance. A pending balance will transfer immediately but the funds will not become available until the original charge becomes available.
3402| statementDescriptor| String | A string to be displayed on the recipient's bank or card statement. This may be at most 22 characters. Attempting to use a statement_descriptor longer than 22 characters will return an error. Note: Most banks will truncate this information and/or display it inconsistently. Some may not display it at all.
3403| sourceType | String | Valid options are: alipay_account, bank_account, bitcoin_receiver, and card.
3404
3405#### Request example
3406```json
3407{
3408 "apiKey": "...",
3409 "amount": 400,
3410 "currency": "usd",
3411 "destination": "acct_1032D82eZvKYlo2C",
3412 "description": "Transfer for test@example.com",
3413}
3414```
3415#### Response example
3416```json
3417{
3418 "callback":"success",
3419 "contextWrites":{
3420 "#":{
3421 "to": {
3422 "id": "tr_18yKar2eZvKYlo2CoN8TUvb6",
3423 "object": "transfer",
3424 "amount": 1,
3425 "amount_reversed": 0,
3426 "application_fee": null,
3427 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
3428 "bank_account": {
3429 "id": "ba_18yKal2eZvKYlo2CeAIrKO9G",
3430 "object": "bank_account",
3431 "account_holder_name": null,
3432 "account_holder_type": null,
3433 "bank_name": "STRIPE TEST BANK",
3434 "country": "US",
3435 "currency": "usd",
3436 "fingerprint": "1JWtPxqbdX5Gamtc",
3437 "last4": "6789",
3438 "routing_number": "110000000",
3439 "status": "new"
3440 },
3441 "created": 1474978913,
3442 "currency": "usd",
3443 "date": 1474978913,
3444 "description": null,
3445 "destination": "ba_18yKal2eZvKYlo2CeAIrKO9G",
3446 "failure_code": null,
3447 "failure_message": null,
3448 "livemode": false,
3449 "metadata": {
3450 "foo": "bar"
3451 },
3452 "method": "standard",
3453 "recipient": "rp_18yKaq2eZvKYlo2CJq5scG7j",
3454 "reversals": {
3455 "object": "list",
3456 "data": [],
3457 "has_more": false,
3458 "total_count": 0,
3459 "url": "/v1/transfers/tr_18yKar2eZvKYlo2CoN8TUvb6/reversals"
3460 },
3461 "reversed": false,
3462 "source_transaction": null,
3463 "source_type": "card",
3464 "statement_descriptor": null,
3465 "status": "paid",
3466 "type": "bank_account"
3467 }
3468 }
3469 }
3470}
3471```
3472
3473<a name="getTransfer"/>
3474## Stripe.getTransfer
3475Retrieves 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.
3476
3477| Field | Type | Description
3478|-----------|------------|----------
3479| apiKey | credentials| The api key obtained from Stripe.
3480| transferId| String | The identifier of the transfer to be retrieved.
3481
3482#### Request example
3483```json
3484{
3485 "apiKey": "...",
3486 "transferId": "tr_18yKar2eZvKYlo2CoN8TUvb6"
3487}
3488```
3489#### Response example
3490```json
3491{
3492 "callback":"success",
3493 "contextWrites":{
3494 "#":{
3495 "to": {
3496 "id": "tr_18yKar2eZvKYlo2CoN8TUvb6",
3497 "object": "transfer",
3498 "amount": 1,
3499 "amount_reversed": 0,
3500 "application_fee": null,
3501 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
3502 "bank_account": {
3503 "id": "ba_18yKal2eZvKYlo2CeAIrKO9G",
3504 "object": "bank_account",
3505 "account_holder_name": null,
3506 "account_holder_type": null,
3507 "bank_name": "STRIPE TEST BANK",
3508 "country": "US",
3509 "currency": "usd",
3510 "fingerprint": "1JWtPxqbdX5Gamtc",
3511 "last4": "6789",
3512 "routing_number": "110000000",
3513 "status": "new"
3514 },
3515 "created": 1474978913,
3516 "currency": "usd",
3517 "date": 1474978913,
3518 "description": null,
3519 "destination": "ba_18yKal2eZvKYlo2CeAIrKO9G",
3520 "failure_code": null,
3521 "failure_message": null,
3522 "livemode": false,
3523 "metadata": {
3524 "foo": "bar"
3525 },
3526 "method": "standard",
3527 "recipient": "rp_18yKaq2eZvKYlo2CJq5scG7j",
3528 "reversals": {
3529 "object": "list",
3530 "data": [],
3531 "has_more": false,
3532 "total_count": 0,
3533 "url": "/v1/transfers/tr_18yKar2eZvKYlo2CoN8TUvb6/reversals"
3534 },
3535 "reversed": false,
3536 "source_transaction": null,
3537 "source_type": "card",
3538 "statement_descriptor": null,
3539 "status": "paid",
3540 "type": "bank_account"
3541 }
3542 }
3543 }
3544}
3545```
3546
3547<a name="updateTransfer"/>
3548## Stripe.updateTransfer
3549Updates the specified transfer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
3550This request accepts only the description and metadata as arguments.
3551| Field | Type | Description
3552|------------|------------|----------
3553| apiKey | credentials| The api key obtained from Stripe.
3554| transferId | String | Id of transfer to update.
3555| description| String | An arbitrary string which you can attach to a transfer object. It is displayed when in the web interface alongside the transfer. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
3556| metadata | JSON | 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 null and then saving. To clear all keys, set metadata to null, then save.
3557
3558#### Request example
3559```json
3560{
3561 "apiKey": "...",
3562 "transferId": "...",
3563 "description": "...",
3564 "metadata": "..."
3565}
3566```
3567#### Response example
3568```json
3569{
3570 "callback":"success",
3571 "contextWrites":{
3572 "#":{
3573 "to": {
3574 "id": "tr_18yKar2eZvKYlo2CoN8TUvb6",
3575 "object": "transfer",
3576 "amount": 1,
3577 "amount_reversed": 0,
3578 "application_fee": null,
3579 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
3580 "bank_account": {
3581 "id": "ba_18yKal2eZvKYlo2CeAIrKO9G",
3582 "object": "bank_account",
3583 "account_holder_name": null,
3584 "account_holder_type": null,
3585 "bank_name": "STRIPE TEST BANK",
3586 "country": "US",
3587 "currency": "usd",
3588 "fingerprint": "1JWtPxqbdX5Gamtc",
3589 "last4": "6789",
3590 "routing_number": "110000000",
3591 "status": "new"
3592 },
3593 "created": 1474978913,
3594 "currency": "usd",
3595 "date": 1474978913,
3596 "description": "Transfer to test@example.com",
3597 "destination": "ba_18yKal2eZvKYlo2CeAIrKO9G",
3598 "failure_code": null,
3599 "failure_message": null,
3600 "livemode": false,
3601 "metadata": {
3602 "foo": "bar"
3603 },
3604 "method": "standard",
3605 "recipient": "rp_18yKaq2eZvKYlo2CJq5scG7j",
3606 "reversals": {
3607 "object": "list",
3608 "data": [
3609
3610 ],
3611 "has_more": false,
3612 "total_count": 0,
3613 "url": "/v1/transfers/tr_18yKar2eZvKYlo2CoN8TUvb6/reversals"
3614 },
3615 "reversed": false,
3616 "source_transaction": null,
3617 "source_type": "card",
3618 "statement_descriptor": null,
3619 "status": "paid",
3620 "type": "bank_account"
3621 }
3622 }
3623 }
3624}
3625```
3626
3627<a name="getTransferList"/>
3628## Stripe.getTransferList
3629Returns 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.
3630
3631| Field | Type | Description
3632|----------------|------------|----------
3633| apiKey | credentials| The api key obtained from Stripe.
3634| destination | String | Only return transfers for the destination specified by this account ID.
3635| recipientstatus| String | Only return transfers for the recipient specified by this recipient ID.
3636| status | String | Only return transfers that have the given status: `pending`, `paid`, `failed`, `in_transit`, or `canceled`.
3637
3638#### Request example
3639```json
3640{
3641 "apiKey": "...",
3642}
3643```
3644#### Response example
3645```json
3646{
3647 "callback":"success",
3648 "contextWrites":{
3649 "#":{
3650 "to": {
3651 "object": "list",
3652 "url": "/v1/transfers",
3653 "has_more": false,
3654 "data": [
3655 {
3656 "id": "tr_18yKar2eZvKYlo2CoN8TUvb6",
3657 "object": "transfer",
3658 "amount": 1,
3659 "amount_reversed": 0,
3660 "application_fee": null,
3661 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
3662 "bank_account": {
3663 "id": "ba_18yKal2eZvKYlo2CeAIrKO9G",
3664 "object": "bank_account",
3665 "account_holder_name": null,
3666 "account_holder_type": null,
3667 "bank_name": "STRIPE TEST BANK",
3668 "country": "US",
3669 "currency": "usd",
3670 "fingerprint": "1JWtPxqbdX5Gamtc",
3671 "last4": "6789",
3672 "routing_number": "110000000",
3673 "status": "new"
3674 },
3675 "created": 1474978913,
3676 "currency": "usd",
3677 "date": 1474978913,
3678 "description": null,
3679 "destination": "ba_18yKal2eZvKYlo2CeAIrKO9G",
3680 "failure_code": null,
3681 "failure_message": null,
3682 "livemode": false,
3683 "metadata": {
3684 "foo": "bar"
3685 },
3686 "method": "standard",
3687 "recipient": "rp_18yKaq2eZvKYlo2CJq5scG7j",
3688 "reversals": {
3689 "object": "list",
3690 "data": [ ],
3691 "has_more": false,
3692 "total_count": 0,
3693 "url": "/v1/transfers/tr_18yKar2eZvKYlo2CoN8TUvb6/reversals"
3694 },
3695 "reversed": false,
3696 "source_transaction": null,
3697 "source_type": "card",
3698 "statement_descriptor": null,
3699 "status": "paid",
3700 "type": "bank_account"
3701 },
3702 {...},
3703 {...}
3704 ]
3705 }
3706 }
3707 }
3708}
3709```
3710
3711<a name="createTransferReversal"/>
3712## Stripe.createTransferReversal
3713When you create a new reversal, you must specify a transfer to create it on.
3714Creating a new reversal on a transfer that has previously been created but not paid out will return the funds to your available balance and refund the fees you were originally charged on the transfer. You may not reverse automatic Stripe transfers.
3715When reversing transfers to Stripe accounts, you can optionally reverse part of the transfer. You can do so as many times as you wish until the entire transfer has been reversed.
3716Once entirely reversed, a transfer can't be reversed again. This method will return an error when called on an already-reversed transfer, or when trying to reverse more money than is left on a transfer.
3717
3718| Field | Type | Description
3719|---------------------|------------|----------
3720| apiKey | credentials| The api key obtained from Stripe.
3721| transferId | credentials| The identifier of the transfer to be reversed.
3722| description | String | An arbitrary string which you can attach to a reversal object. It is displayed alongside the reversal in the dashboard. This will be unset if you POST an empty value.
3723| metadata | String | A set of key/value pairs that you can attach to a reversal object. It can be useful for storing additional information about the reversal in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
3724| refundApplicationFee| String | Boolean indicating whether the application fee should be refunded when reversing this transfer. If a full transfer reversal is given, the full application fee will be refunded. Otherwise, the application fee will be refunded with an amount proportional to the amount of the transfer reversed.
3725
3726#### Request example
3727```json
3728{ "apiKey": "...",
3729 "transferId": "tr_191bZGH8tdm6eq3TKKWZ0DtJ",
3730}
3731```
3732#### Response example
3733```json
3734{
3735 "callback":"success",
3736 "contextWrites":{
3737 "#":{
3738 "to": {
3739 "id": "trr_191bZGH8tdm6eq3TQjfYF2bx",
3740 "object": "transfer_reversal",
3741 "amount": 1100,
3742 "balance_transaction": null,
3743 "created": 1475759146,
3744 "currency": "usd",
3745 "metadata": {
3746 },
3747 "transfer": "tr_191bZGH8tdm6eq3TKKWZ0DtJ"
3748 }
3749 }
3750 }
3751}
3752```
3753
3754<a name="getTransferReversal"/>
3755## Stripe.getTransferReversal
3756Method By default, you can see the 10 most recent reversals stored directly on the transfer object, but you can also retrieve details about a specific reversal stored on the transfer.
3757
3758
3759| Field | Type | Description
3760|-----------|------------|----------
3761| apiKey | credentials| The api key obtained from Stripe.
3762| id | String | ID of reversal to retrieve.
3763| transferId| String | ID of the transfer reversed.
3764
3765#### Request example
3766```json
3767{
3768 "apiKey": "...",
3769 "id": "trr_18wHEl2eZvKYlo2CIIzWDBVe",
3770 "transferId": "tr_18yKar2eZvKYlo2CoN8TUvb6"
3771}
3772```
3773#### Response example
3774```json
3775{
3776 "callback":"success",
3777 "contextWrites":{
3778 "#":{
3779 "to":{
3780 "id": "trr_18wHEl2eZvKYlo2CIIzWDBVe",
3781 "object": "transfer_reversal",
3782 "amount": 5000,
3783 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
3784 "created": 1474489355,
3785 "currency": "usd",
3786 "metadata": {
3787 },
3788 "transfer": "tr_18wHEj2eZvKYlo2CmoWPui9Y"
3789 }
3790 }
3791 }
3792}
3793```
3794
3795<a name="updateTransferReversal"/>
3796## Stripe.updateTransferReversal
3797Updates the specified reversal by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
3798
3799| Field | Type | Description
3800|------------|------------|----------
3801| apiKey | credentials| The api key obtained from Stripe.
3802| id | String | ID of reversal to retrieve.
3803| transferId | String | ID of the transfer reversed.
3804| metadata | JSON | A set of key/value pairs that you can attach to a reversal object. It can be useful for storing additional information about the reversal in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
3805| description| String | An arbitrary string which you can attach to a reversal object. It is displayed when in the web interface alongside the reversal. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
3806
3807#### Request example
3808```json
3809{
3810 "apiKey": "...",
3811 "id": "trr_18wHEl2eZvKYlo2CIIzWDBVe",
3812 "transferId": "tr_18wHEj2eZvKYlo2CmoWPui9Y",
3813 "metadata": { \"order_id\": \"6735\" },
3814}
3815```
3816#### Response example
3817```json
3818{
3819 "callback":"success",
3820 "contextWrites":{
3821 "#":{
3822 "to": {
3823 "id": "trr_18wHEl2eZvKYlo2CIIzWDBVe",
3824 "object": "transfer_reversal",
3825 "amount": 5000,
3826 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
3827 "created": 1474489355,
3828 "currency": "usd",
3829 "metadata": {
3830 "key": "value"
3831 },
3832 "transfer": "tr_18wHEj2eZvKYlo2CmoWPui9Y"
3833 }
3834 }
3835 }
3836}
3837```
3838
3839<a name="getTransferReversalList"/>
3840## Stripe.getTransferReversalList
3841You can see a list of the reversals belonging to a specific transfer. Note that the 10 most recent reversals are always available by default on the transfer object.
3842
3843| Field | Type | Description
3844|-----------|------------|----------
3845| apiKey | credentials| The api key obtained from Stripe.
3846| transferId| String | The ID of the transfer whose reversals will be retrieved.
3847
3848#### Request example
3849```json
3850{
3851 "apiKey": "...",
3852 "transferId": "tr_18yKar2eZvKYlo2CoN8TUvb6"
3853}
3854```
3855#### Response example
3856```json
3857{
3858 "callback":"success",
3859 "contextWrites":{
3860 "#":{
3861 "to": {
3862 "object": "list",
3863 "url": "/v1/transfers/tr_18yKar2eZvKYlo2CoN8TUvb6/reversals",
3864 "has_more": false,
3865 "data": [
3866 {
3867 "id": "trr_18wHEl2eZvKYlo2CIIzWDBVe",
3868 "object": "transfer_reversal",
3869 "amount": 5000,
3870 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
3871 "created": 1474489355,
3872 "currency": "usd",
3873 "metadata": {
3874 },
3875 "transfer": "tr_18wHEj2eZvKYlo2CmoWPui9Y"
3876 },
3877 {...},
3878 {...}
3879 ]
3880 }
3881 }
3882 }
3883}
3884```
3885
3886<a name="createAccount"/>
3887## Stripe.createAccount
3888With Connect, you can create Stripe accounts for your users. To do this, you'll first need to register your platform.
3889
3890| Field | Type | Description
3891|--------|------------|----------
3892| apiKey | credentials| The api key obtained from Stripe.
3893| country| String | The country the account holder resides in or that the business is legally established in. For example, if you are in the United States and the business you’re creating an account for is legally represented in Canada, you would use “CA†as the country for the account being created.
3894| email | String | The email address of the account holder. For standalone accounts, Stripe will email your user with instructions for how to set up their account. For managed accounts, this is only to make the account easier to identify to you: Stripe will never directly reach out to your users.
3895| managed| String | Whether you'd like to create a managed or standalone account. Managed accounts have extra parameters available to them, and require that you, the platform, handle all communication with the account holder. Standalone accounts are normal Stripe accounts: Stripe will email the account holder to setup a username and password, and handle all account management directly with them.
3896
3897#### Request example
3898```json
3899{
3900 "apiKey": "...",
3901 "country": "US",
3902 "email": "bob@example.com'",
3903 "managed": "true"
3904}
3905```
3906#### Response example
3907```json
3908{
3909 "callback":"success",
3910 "contextWrites":{
3911 "#":{
3912 "to": {
3913 "id": "acct_1032D82eZvKYlo2C",
3914 "object": "account",
3915 "business_logo": null,
3916 "business_name": "Stripe.com",
3917 "business_url": null,
3918 "charges_enabled": false,
3919 "country": "US",
3920 "debit_negative_balances": true,
3921 "decline_charge_on": {
3922 "avs_failure": true,
3923 "cvc_failure": false
3924 },
3925 "default_currency": "usd",
3926 "details_submitted": false,
3927 "display_name": "Stripe.com",
3928 "email": "bob@example.com",
3929 "external_accounts": {
3930 "object": "list",
3931 "data": [],
3932 "has_more": false,
3933 "total_count": 0,
3934 "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
3935 },
3936 "legal_entity": {
3937 "address": {
3938 "city": null,
3939 "country": "US",
3940 "line1": null,
3941 "line2": null,
3942 "postal_code": null,
3943 "state": null
3944 },
3945 "business_name": null,
3946 "business_tax_id_provided": false,
3947 "dob": {
3948 "day": null,
3949 "month": null,
3950 "year": null
3951 },
3952 "first_name": null,
3953 "last_name": null,
3954 "personal_address": {
3955 "city": null,
3956 "country": "US",
3957 "line1": null,
3958 "line2": null,
3959 "postal_code": null,
3960 "state": null
3961 },
3962 "personal_id_number_provided": false,
3963 "ssn_last_4_provided": false,
3964 "type": null,
3965 "verification": {
3966 "details": null,
3967 "details_code": "failed_other",
3968 "document": null,
3969 "status": "unverified"
3970 }
3971 },
3972 "managed": false,
3973 "product_description": null,
3974 "statement_descriptor": null,
3975 "support_email": null,
3976 "support_phone": null,
3977 "timezone": "US/Pacific",
3978 "tos_acceptance": {
3979 "date": null,
3980 "ip": null,
3981 "user_agent": null
3982 },
3983 "transfer_schedule": {
3984 "delay_days": 7,
3985 "interval": "daily"
3986 },
3987 "transfers_enabled": false,
3988 "verification": {
3989 "disabled_reason": "fields_needed",
3990 "due_by": null,
3991 "fields_needed": [
3992 "business_url",
3993 "external_account",
3994 "product_description",
3995 "support_phone",
3996 "tos_acceptance.date",
3997 "tos_acceptance.ip"
3998 ]
3999 },
4000 "keys": {
4001 "secret": "sk_test_YXPYjAOEIIJOhEszvghLNMFw",
4002 "publishable": "pk_test_kGAoWInjeNfXVOuRl84TJFgP"
4003 }
4004 }
4005 }
4006 }
4007}
4008```
4009
4010<a name="getAccount"/>
4011## Stripe.getAccount
4012Retrieves the details of the account.
4013
4014| Field | Type | Description
4015|----------|------------|----------
4016| apiKey | credentials| The api key obtained from Stripe.
4017| accountId| String | Id of account to retrive
4018
4019#### Request example
4020```json
4021{
4022 "apiKey": "...",
4023 "accountId": "acct_1032D82eZvKYlo2C"
4024}
4025```
4026#### Response example
4027```json
4028{
4029 "callback":"success",
4030 "contextWrites":{
4031 "#":{
4032 "to": {
4033 "id": "acct_1032D82eZvKYlo2C",
4034 "object": "account",
4035 "business_logo": null,
4036 "business_name": "Stripe.com",
4037 "business_url": null,
4038 "charges_enabled": false,
4039 "country": "US",
4040 "debit_negative_balances": true,
4041 "decline_charge_on": {
4042 "avs_failure": true,
4043 "cvc_failure": false
4044 },
4045 "default_currency": "usd",
4046 "details_submitted": false,
4047 "display_name": "Stripe.com",
4048 "email": "site@stripe.com",
4049 "external_accounts": {
4050 "object": "list",
4051 "data": [],
4052 "has_more": false,
4053 "total_count": 0,
4054 "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
4055 },
4056 "legal_entity": {
4057 "address": {
4058 "city": null,
4059 "country": "US",
4060 "line1": null,
4061 "line2": null,
4062 "postal_code": null,
4063 "state": null
4064 },
4065 "business_name": null,
4066 "business_tax_id_provided": false,
4067 "dob": {
4068 "day": null,
4069 "month": null,
4070 "year": null
4071 },
4072 "first_name": null,
4073 "last_name": null,
4074 "personal_address": {
4075 "city": null,
4076 "country": "US",
4077 "line1": null,
4078 "line2": null,
4079 "postal_code": null,
4080 "state": null
4081 },
4082 "personal_id_number_provided": false,
4083 "ssn_last_4_provided": false,
4084 "type": null,
4085 "verification": {
4086 "details": null,
4087 "details_code": "failed_other",
4088 "document": null,
4089 "status": "unverified"
4090 }
4091 },
4092 "managed": false,
4093 "product_description": null,
4094 "statement_descriptor": null,
4095 "support_email": null,
4096 "support_phone": null,
4097 "timezone": "US/Pacific",
4098 "tos_acceptance": {
4099 "date": null,
4100 "ip": null,
4101 "user_agent": null
4102 },
4103 "transfer_schedule": {
4104 "delay_days": 7,
4105 "interval": "daily"
4106 },
4107 "transfers_enabled": false,
4108 "verification": {
4109 "disabled_reason": "fields_needed",
4110 "due_by": null,
4111 "fields_needed": [
4112 "business_url",
4113 "external_account",
4114 "product_description",
4115 "support_phone",
4116 "tos_acceptance.date",
4117 "tos_acceptance.ip"
4118 ]
4119 }
4120 }
4121 }
4122 }
4123}
4124```
4125
4126<a name="updateAccount"/>
4127## Stripe.updateAccount
4128Updates an account by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
4129You may only update accounts that you manage.
4130
4131| Field | Type | Description
4132|----------------------|------------|----------
4133| apiKey | credentials| The api key obtained from Stripe.
4134| accountId | String | Id of account to update
4135| businessLogo | String | Bussines logo
4136| businessName | String | The publicly sharable name for this account.
4137| businessPrimaryColor | String | A CSS hex color value representing the primary branding color for this account
4138| businessUrl | String | The URL that best shows the service or product provided for this account
4139| debitNegativeBalances| String | A boolean for whether or not Stripe should try to reclaim negative balances from the account holder’s bank account.
4140| declineChargeOn | String | Account-level settings to automatically decline certain types of charges regardless of the bank’s decision.
4141| defaultCurrency | String | Three-letter ISO currency code representing the default currency for the account.
4142| email | String | Email address of the account holder. For standalone accounts, this is used to email them asking them to claim their Stripe account. For managed accounts, this is only to make the account easier to identify to you: Stripe will not email the account holder.
4143| externalAccount | String | A card or bank account to attach to the account. You can provide either a token, like the ones returned by Stripe.js, or a dictionary as documented in the external_account parameter for either card or bank account creation.
4144| legalEntity | String | Information about the account holder; varies by account country and account status.
4145| metadata | JSON | A set of key/value pairs that you can attach to an account object. It can be useful for storing additional information about the account in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
4146| productDescription | String | Internal-only description of the product being sold or service being provided by this account. It’s used by Stripe for risk and underwriting purposes.
4147| statementDescriptor | String | The text that will appear on credit card statements by default if a charge is being made directly on the account.
4148| supportEmail | String | A publicly shareable email address that can be reached for support for this account
4149| supportPhone | String | A publicly shareable phone number that can be reached for support for this account
4150| supportUrl | String | A publicly shareable URL that can be reached for support for this account
4151| tosAcceptance | JSON | Details on who accepted the Stripe terms of service, and when they accepted it
4152| transferSchedule | JSON | Details on when this account will make funds from charges available, and when they will be paid out to the account holder’s bank account.
4153
4154#### Request example
4155```json
4156{
4157 "apiKey": "...",
4158 "accountId": "acct_1032D82eZvKYlo2C",
4159 "supportPhone": "555-867-5309",
4160}
4161```
4162#### Response example
4163```json
4164{
4165 "callback":"success",
4166 "contextWrites":{
4167 "#":{
4168 "to":{
4169 "id": "acct_1032D82eZvKYlo2C",
4170 "object": "account",
4171 "business_logo": null,
4172 "business_name": "Stripe.com",
4173 "business_url": null,
4174 "charges_enabled": false,
4175 "country": "US",
4176 "debit_negative_balances": true,
4177 "decline_charge_on": {
4178 "avs_failure": true,
4179 "cvc_failure": false
4180 },
4181 "default_currency": "usd",
4182 "details_submitted": false,
4183 "display_name": "Stripe.com",
4184 "email": "site@stripe.com",
4185 "external_accounts": {
4186 "object": "list",
4187 "data": [],
4188 "has_more": false,
4189 "total_count": 0,
4190 "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
4191 },
4192 "legal_entity": {
4193 "address": {
4194 "city": null,
4195 "country": "US",
4196 "line1": null,
4197 "line2": null,
4198 "postal_code": null,
4199 "state": null
4200 },
4201 "business_name": null,
4202 "business_tax_id_provided": false,
4203 "dob": {
4204 "day": null,
4205 "month": null,
4206 "year": null
4207 },
4208 "first_name": null,
4209 "last_name": null,
4210 "personal_address": {
4211 "city": null,
4212 "country": "US",
4213 "line1": null,
4214 "line2": null,
4215 "postal_code": null,
4216 "state": null
4217 },
4218 "personal_id_number_provided": false,
4219 "ssn_last_4_provided": false,
4220 "type": null,
4221 "verification": {
4222 "details": null,
4223 "details_code": "failed_other",
4224 "document": null,
4225 "status": "unverified"
4226 }
4227 },
4228 "managed": false,
4229 "product_description": null,
4230 "statement_descriptor": null,
4231 "support_email": null,
4232 "support_phone": "555-867-5309",
4233 "timezone": "US/Pacific",
4234 "tos_acceptance": {
4235 "date": null,
4236 "ip": null,
4237 "user_agent": null
4238 },
4239 "transfer_schedule": {
4240 "delay_days": 7,
4241 "interval": "daily"
4242 },
4243 "transfers_enabled": false,
4244 "verification": {
4245 "disabled_reason": "fields_needed",
4246 "due_by": null,
4247 "fields_needed": [
4248 "business_url",
4249 "external_account",
4250 "product_description",
4251 "support_phone",
4252 "tos_acceptance.date",
4253 "tos_acceptance.ip"
4254 ]
4255 }
4256 }
4257 }
4258 }
4259}
4260```
4261
4262<a name="deleteAccount"/>
4263## Stripe.deleteAccount
4264With Connect, you may delete Stripe accounts you manage.
4265Managed accounts created using test-mode keys can be deleted at any time. Managed accounts created using live-mode keys may only be deleted once all balances are zero.
4266If you are looking to close your own account, use the data tab in your account settings instead.
4267
4268| Field | Type | Description
4269|----------|------------|----------
4270| apiKey | credentials| The api key obtained from Stripe.
4271| accountId| String | Id of account to delete
4272
4273#### Request example
4274```json
4275{
4276 "apiKey": "...",
4277 "accountId": "acct_1032D82eZvKYlo2C"
4278}
4279```
4280#### Response example
4281```json
4282{
4283 "callback":"success",
4284 "contextWrites":{
4285 "#":{
4286 "to":{
4287 "deleted": true,
4288 "id": "acct_1032D82eZvKYlo2C"
4289 }
4290 }
4291 }
4292}
4293```
4294
4295<a name="rejectAccount"/>
4296## Stripe.rejectAccount
4297Managed accounts created using test-mode keys can be rejected at any time. Managed accounts created using live-mode keys may only be rejected once all balances are zero.
4298
4299| Field | Type | Description
4300|----------|------------|----------
4301| apiKey | credentials| The api key obtained from Stripe.
4302| accountId| String | Id of account to reject
4303| reason | String | The reason for rejecting the account. May be one of `fraud`, `terms_of_service`, or `other`.
4304
4305#### Request example
4306```json
4307{
4308 "apiKey": "...",
4309 "accountId": "acct_1032D82eZvKYlo2C",
4310 "reason": "fraud"
4311}
4312```
4313#### Response example
4314```json
4315{
4316 "callback":"success",
4317 "contextWrites":{
4318 "#":{
4319 "to": {
4320 "id": "acct_1032D82eZvKYlo2C",
4321 "object": "account",
4322 "business_logo": null,
4323 "business_name": "Stripe.com",
4324 "business_url": null,
4325 "charges_enabled": false,
4326 "country": "US",
4327 "debit_negative_balances": true,
4328 "decline_charge_on": {
4329 "avs_failure": true,
4330 "cvc_failure": false
4331 },
4332 "default_currency": "usd",
4333 "details_submitted": false,
4334 "display_name": "Stripe.com",
4335 "email": "site@stripe.com",
4336 "external_accounts": {
4337 "object": "list",
4338 "data": [],
4339 "has_more": false,
4340 "total_count": 0,
4341 "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
4342 },
4343 "legal_entity": {
4344 "address": {
4345 "city": null,
4346 "country": "US",
4347 "line1": null,
4348 "line2": null,
4349 "postal_code": null,
4350 "state": null
4351 },
4352 "business_name": null,
4353 "business_tax_id_provided": false,
4354 "dob": {
4355 "day": null,
4356 "month": null,
4357 "year": null
4358 },
4359 "first_name": null,
4360 "last_name": null,
4361 "personal_address": {
4362 "city": null,
4363 "country": "US",
4364 "line1": null,
4365 "line2": null,
4366 "postal_code": null,
4367 "state": null
4368 },
4369 "personal_id_number_provided": false,
4370 "ssn_last_4_provided": false,
4371 "type": null,
4372 "verification": {
4373 "details": null,
4374 "details_code": "failed_other",
4375 "document": null,
4376 "status": "unverified"
4377 }
4378 },
4379 "managed": false,
4380 "product_description": null,
4381 "statement_descriptor": null,
4382 "support_email": null,
4383 "support_phone": null,
4384 "timezone": "US/Pacific",
4385 "tos_acceptance": {
4386 "date": null,
4387 "ip": null,
4388 "user_agent": null
4389 },
4390 "transfer_schedule": {
4391 "delay_days": 7,
4392 "interval": "daily"
4393 },
4394 "transfers_enabled": false,
4395 "verification": {
4396 "disabled_reason": "rejected.fraud"
4397 }
4398 }
4399 }
4400 }
4401}
4402```
4403
4404<a name="getAccountList"/>
4405## Stripe.getAccountList
4406Returns a list of accounts connected to your platform via Connect. If you’re not a platform, the list will be empty.
4407
4408| Field | Type | Description
4409|--------------|------------|----------
4410| apiKey | credentials| The api key obtained from Stripe.
4411| endingBefore | String | 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.
4412| limit | Number | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
4413| startingAfter| String | 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.
4414
4415#### Request example
4416```json
4417{
4418 "apiKey": "...",
4419 "endingBefore": "...",
4420 "limit": 0,
4421 "startingAfter": "..."
4422}
4423```
4424#### Response example
4425```json
4426{
4427 "callback":"success",
4428 "contextWrites":{
4429 "#":{
4430 "to": {
4431 "object": "list",
4432 "url": "/v1/accounts",
4433 "has_more": false,
4434 "data": [
4435 {
4436 "id": "acct_1032D82eZvKYlo2C",
4437 "object": "account",
4438 "business_logo": null,
4439 "business_name": "Stripe.com",
4440 "business_url": null,
4441 "charges_enabled": false,
4442 "country": "US",
4443 "debit_negative_balances": true,
4444 "decline_charge_on": {
4445 "avs_failure": true,
4446 "cvc_failure": false
4447 },
4448 "default_currency": "usd",
4449 "details_submitted": false,
4450 "display_name": "Stripe.com",
4451 "email": "site@stripe.com",
4452 "external_accounts": {
4453 "object": "list",
4454 "data": [],
4455 "has_more": false,
4456 "total_count": 0,
4457 "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts"
4458 },
4459 "legal_entity": {
4460 "address": {
4461 "city": null,
4462 "country": "US",
4463 "line1": null,
4464 "line2": null,
4465 "postal_code": null,
4466 "state": null
4467 },
4468 "business_name": null,
4469 "business_tax_id_provided": false,
4470 "dob": {
4471 "day": null,
4472 "month": null,
4473 "year": null
4474 },
4475 "first_name": null,
4476 "last_name": null,
4477 "personal_address": {
4478 "city": null,
4479 "country": "US",
4480 "line1": null,
4481 "line2": null,
4482 "postal_code": null,
4483 "state": null
4484 },
4485 "personal_id_number_provided": false,
4486 "ssn_last_4_provided": false,
4487 "type": null,
4488 "verification": {
4489 "details": null,
4490 "details_code": "failed_other",
4491 "document": null,
4492 "status": "unverified"
4493 }
4494 },
4495 "managed": false,
4496 "product_description": null,
4497 "statement_descriptor": null,
4498 "support_email": null,
4499 "support_phone": null,
4500 "timezone": "US/Pacific",
4501 "tos_acceptance": {
4502 "date": null,
4503 "ip": null,
4504 "user_agent": null
4505 },
4506 "transfer_schedule": {
4507 "delay_days": 7,
4508 "interval": "daily"
4509 },
4510 "transfers_enabled": false,
4511 "verification": {
4512 "disabled_reason": "fields_needed",
4513 "due_by": null,
4514 "fields_needed": [
4515 "business_url",
4516 "external_account",
4517 "product_description",
4518 "support_phone",
4519 "tos_acceptance.date",
4520 "tos_acceptance.ip"
4521 ]
4522 }
4523 },
4524 {...},
4525 {...}
4526 ]
4527 }
4528 }
4529 }
4530}
4531```
4532
4533<a name="createFeeRefund"/>
4534## Stripe.createFeeRefund
4535Refunds an application fee that has previously been collected but not yet refunded. Funds will be refunded to the Stripe account that the fee was originally collected from.
4536You can optionally refund only part of an application fee. You can do so as many times as you wish until the entire fee has been refunded.
4537Once entirely refunded, an application fee can't be refunded again. This method will throw an error when called on an already-refunded application fee, or when trying to refund more money than is left on an application fee.
4538
4539| Field | Type | Description
4540|---------|------------|----------
4541| apiKey | credentials| The api key obtained from Stripe.
4542| appId | String | The identifier of the application fee to be refunded.
4543| amount | Number | A positive integer in cents representing how much of this fee to refund. Can only refund up to the unrefunded amount remaining of the fee.
4544| metadata| JSON | A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
4545
4546#### Request example
4547```json
4548{
4549 "apiKey": "...",
4550 "appId": "fee_9EkkFV1uz0mEyZ",
4551}
4552```
4553#### Response example
4554```json
4555{
4556 "callback":"success",
4557 "contextWrites":{
4558 "#":{
4559 "to": {
4560 "id": "fr_9IgOA4JPFLwylO",
4561 "object": "fee_refund",
4562 "amount": 100,
4563 "balance_transaction": null,
4564 "created": 1475395716,
4565 "currency": "usd",
4566 "fee": "fee_9EkkFV1uz0mEyZ",
4567 "metadata": {
4568 },
4569 "refunded": true
4570 }
4571 }
4572 }
4573}
4574```
4575
4576<a name="getFeeRefund"/>
4577## Stripe.getFeeRefund
4578By default, you can see the 10 most recent refunds stored directly on the application fee object, but you can also retrieve details about a specific refund stored on the application fee.
4579
4580| Field | Type | Description
4581|---------|------------|----------
4582| apiKey | credentials| The api key obtained from Stripe.
4583| feeId | String | ID of the application fee refunded.
4584| refundId| String | ID of refund to retrieve.
4585
4586#### Request example
4587```json
4588{
4589 "apiKey": "...",
4590 "feeId": "fee_9EkkFV1uz0mEyZ",
4591 "refundId": "fr_9I0kzxDiLcgFxX"
4592}
4593```
4594#### Response example
4595```json
4596{
4597 "callback":"success",
4598 "contextWrites":{
4599 "#":{
4600 "to":{
4601 "id": "fr_9I0kzxDiLcgFxX",
4602 "object": "fee_refund",
4603 "amount": 100,
4604 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
4605 "created": 1475240830,
4606 "currency": "usd",
4607 "fee": "fee_9EkkFV1uz0mEyZ",
4608 "metadata": {
4609 }
4610 }
4611 }
4612 }
4613}
4614```
4615
4616<a name="updateFeeRefund"/>
4617## Stripe.updateFeeRefund
4618Updates the specified application fee refund by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
4619This request only accepts metadata as an argument.
4620
4621| Field | Type | Description
4622|---------|------------|----------
4623| apiKey | credentials| The api key obtained from Stripe.
4624| feeId | String | ID of the application fee refunded.
4625| refundId| String | ID of refund to retrieve.
4626| metadata| JSON | A set of key/value pairs that you can attach to an application fee refund object. It can be useful for storing additional information about the refund in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
4627
4628#### Request example
4629```json
4630{
4631 "apiKey": "...",
4632 "feeId": "fee_9EkkFV1uz0mEyZ",
4633 "refundId": "fr_9I0kzxDiLcgFxX",
4634 "metadata": "{ \"order_id\": \"6735\"}"
4635}
4636```
4637#### Response example
4638```json
4639{
4640 "callback":"success",
4641 "contextWrites":{
4642 "#":{
4643 "to":{
4644 "id": "fr_9I0kzxDiLcgFxX",
4645 "object": "fee_refund",
4646 "amount": 100,
4647 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
4648 "created": 1475240830,
4649 "currency": "usd",
4650 "fee": "fee_9EkkFV1uz0mEyZ",
4651 "metadata": {
4652 "key": "value"
4653 }
4654 }
4655 }
4656 }
4657}
4658```
4659
4660<a name="getFeeRefundList"/>
4661## Stripe.getFeeRefundList
4662You can see a list of the refunds belonging to a specific application fee. Note that the 10 most recent refunds are always available by default on the application fee object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional refunds.
4663
4664| Field | Type | Description
4665|--------------|------------|----------
4666| apiKey | credentials| The api key obtained from Stripe.
4667| appId | String | The ID of the application fee whose refunds will be retrieved.
4668| endingBefore | String | 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.
4669| limit | Number | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
4670| startingAfter| String | 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.
4671
4672#### Request example
4673```json
4674{
4675 "apiKey": "...",
4676 "appId": "fee_9EkkFV1uz0mEyZ",
4677}
4678```
4679#### Response example
4680```json
4681{
4682 "callback":"success",
4683 "contextWrites":{
4684 "#":{
4685 "to":{
4686 "object": "list",
4687 "url": "/v1/application_fees/fee_9EkkFV1uz0mEyZ/refunds",
4688 "has_more": false,
4689 "data": [
4690 {
4691 "id": "fr_9I0kzxDiLcgFxX",
4692 "object": "fee_refund",
4693 "amount": 100,
4694 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
4695 "created": 1475240830,
4696 "currency": "usd",
4697 "fee": "fee_9EkkFV1uz0mEyZ",
4698 "metadata": {
4699 }
4700 },
4701 {...},
4702 {...}
4703 ]
4704 }
4705 }
4706 }
4707}
4708```
4709
4710<a name="getApplicationFee"/>
4711## Stripe.getApplicationFee
4712Retrieves the details of an application fee that your account has collected. The same information is returned when refunding the application fee.
4713
4714| Field | Type | Description
4715|-------|------------|----------
4716| apiKey| credentials| The api key obtained from Stripe.
4717| feeId | String | The identifier of the fee to be retrieved.
4718
4719#### Request example
4720```json
4721{
4722 "apiKey": "...",
4723 "feeId": "fee_9EkkFV1uz0mEyZ"
4724}
4725```
4726#### Response example
4727```json
4728{
4729 "callback":"success",
4730 "contextWrites":{
4731 "#":{
4732 "to": {
4733 "id": "fee_9EkkFV1uz0mEyZ",
4734 "object": "application_fee",
4735 "account": "acct_181heUI2xUg5aQMA",
4736 "amount": 1000,
4737 "amount_refunded": 1000,
4738 "application": "ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7",
4739 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
4740 "charge": "py_18wHEjI2xUg5aQMAsAX1AYPD",
4741 "created": 1474489353,
4742 "currency": "usd",
4743 "livemode": false,
4744 "originating_transaction": "tr_18wHEj2eZvKYlo2CmoWPui9Y",
4745 "refunded": true,
4746 "refunds": {
4747 "object": "list",
4748 "data": [
4749 {
4750 "id": "fr_9EkkTaYshcJogQ",
4751 "object": "fee_refund",
4752 "amount": 1000,
4753 "balance_transaction": "txn_18wHEm2eZvKYlo2Ch4blmHzq",
4754 "created": 1474489355,
4755 "currency": "usd",
4756 "fee": "fee_9EkkFV1uz0mEyZ",
4757 "metadata": {
4758 }
4759 }
4760 ],
4761 "has_more": false,
4762 "total_count": 1,
4763 "url": "/v1/application_fees/fee_9EkkFV1uz0mEyZ/refunds"
4764 }
4765 }
4766 }
4767 }
4768}
4769```
4770
4771<a name="getApplicationFeeList"/>
4772## Stripe.getApplicationFeeList
4773Returns a list of application fees you’ve previously collected. The application fees are returned in sorted order, with the most recent fees appearing first.
4774
4775| Field | Type | Description
4776|--------------|------------|----------
4777| apiKey | credentials| The api key obtained from Stripe.
4778| chargeId | String | Only return application fees for the charge specified by this charge ID.
4779| endingBefore | String | 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.
4780| limit | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
4781| startingAfter| String | 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.
4782
4783#### Request example
4784```json
4785{ "apiKey": ,
4786}
4787```
4788#### Response example
4789```json
4790{
4791 "callback":"success",
4792 "contextWrites":{
4793 "#":{
4794 "to":{
4795 "object": "list",
4796 "url": "/v1/application_fees",
4797 "has_more": false,
4798 "data": [
4799 {
4800 "id": "fee_9EkkFV1uz0mEyZ",
4801 "object": "application_fee",
4802 "account": "acct_181heUI2xUg5aQMA",
4803 "amount": 1000,
4804 "amount_refunded": 1000,
4805 "application": "ca_32D88BD1qLklliziD7gYQvctJIhWBSQ7",
4806 "balance_transaction": "txn_18tiU12eZvKYlo2CetxoRTDG",
4807 "charge": "py_18wHEjI2xUg5aQMAsAX1AYPD",
4808 "created": 1474489353,
4809 "currency": "usd",
4810 "livemode": false,
4811 "originating_transaction": "tr_18wHEj2eZvKYlo2CmoWPui9Y",
4812 "refunded": true,
4813 "refunds": {
4814 "object": "list",
4815 "data": [
4816 {
4817 "id": "fr_9EkkTaYshcJogQ",
4818 "object": "fee_refund",
4819 "amount": 1000,
4820 "balance_transaction": "txn_18wHEm2eZvKYlo2Ch4blmHzq",
4821 "created": 1474489355,
4822 "currency": "usd",
4823 "fee": "fee_9EkkFV1uz0mEyZ",
4824 "metadata": {
4825 }
4826 }
4827 ],
4828 "has_more": false,
4829 "total_count": 1,
4830 "url": "/v1/application_fees/fee_9EkkFV1uz0mEyZ/refunds"
4831 }
4832 },
4833 {...},
4834 {...}
4835 ]
4836 }
4837 }
4838 }
4839}
4840```
4841
4842<a name="getCountrySpecsList"/>
4843## Stripe.getCountrySpecsList
4844Lists all Country Spec objects available in the API.
4845
4846| Field | Type | Description
4847|--------------|------------|----------
4848| apiKey | credentials| The api key obtained from Stripe.
4849| endingBefore | String | 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.
4850| limit | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
4851| startingAfter| String | 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.
4852
4853#### Request example
4854```json
4855{
4856 "apiKey": "...",
4857}
4858```
4859#### Response example
4860```json
4861{
4862 "callback":"success",
4863 "contextWrites":{
4864 "#":{
4865 "to":{
4866 "object": "list",
4867 "url": "/v1/country_specs",
4868 "has_more": false,
4869 "data": [
4870 {
4871 "id": "US",
4872 "object": "country_spec",
4873 "default_currency": "usd",
4874 "supported_bank_account_currencies": {
4875 "usd": [
4876 "US"
4877 ]
4878 },
4879 "supported_payment_currencies": [
4880 "usd",
4881 "aed",
4882 "afn",
4883 "..."
4884 ],
4885 "supported_payment_methods": [
4886 "alipay",
4887 "card",
4888 "stripe"
4889 ],
4890 "verification_fields": {
4891 "individual": {
4892 "minimum": [
4893 "external_account",
4894 "legal_entity.address.city",
4895 "legal_entity.address.line1",
4896 "legal_entity.address.postal_code",
4897 "legal_entity.address.state",
4898 "legal_entity.dob.day",
4899 "legal_entity.dob.month",
4900 "legal_entity.dob.year",
4901 "legal_entity.first_name",
4902 "legal_entity.last_name",
4903 "legal_entity.ssn_last_4",
4904 "legal_entity.type",
4905 "tos_acceptance.date",
4906 "tos_acceptance.ip"
4907 ],
4908 "additional": [
4909 "legal_entity.personal_id_number",
4910 "legal_entity.verification.document"
4911 ]
4912 },
4913 "company": {
4914 "minimum": [
4915 "external_account",
4916 "legal_entity.address.city",
4917 "legal_entity.address.line1",
4918 "legal_entity.address.postal_code",
4919 "legal_entity.address.state",
4920 "legal_entity.business_name",
4921 "legal_entity.business_tax_id",
4922 "legal_entity.dob.day",
4923 "legal_entity.dob.month",
4924 "legal_entity.dob.year",
4925 "legal_entity.first_name",
4926 "legal_entity.last_name",
4927 "legal_entity.ssn_last_4",
4928 "legal_entity.type",
4929 "tos_acceptance.date",
4930 "tos_acceptance.ip"
4931 ],
4932 "additional": [
4933 "legal_entity.personal_id_number",
4934 "legal_entity.verification.document"
4935 ]
4936 }
4937 }
4938 },
4939 {...},
4940 {...}
4941 ]
4942 }
4943 }
4944 }
4945}
4946```
4947
4948<a name="getCountrySpec"/>
4949## Stripe.getCountrySpec
4950Returns a Country Spec for a given Country code.
4951
4952| Field | Type | Description
4953|--------|------------|----------
4954| apiKey | credentials| The api key obtained from Stripe.
4955| country| String | An ISO country code. Available country codes can be listed with the List Country Specs endpoint.
4956
4957#### Request example
4958```json
4959{
4960 "apiKey": "...",
4961 "country": "US"
4962}
4963```
4964#### Response example
4965```json
4966{
4967 "callback":"success",
4968 "contextWrites":{
4969 "#":{
4970 "to":{
4971 "id": "US",
4972 "object": "country_spec",
4973 "default_currency": "usd",
4974 "supported_bank_account_currencies": {
4975 "usd": [
4976 "US"
4977 ]
4978 },
4979 "supported_payment_currencies": [
4980 "usd",
4981 "aed",
4982 "afn",
4983 "..."
4984 ],
4985 "supported_payment_methods": [
4986 "alipay",
4987 "card",
4988 "stripe"
4989 ],
4990 "verification_fields": {
4991 "individual": {
4992 "minimum": [
4993 "external_account",
4994 "legal_entity.address.city",
4995 "legal_entity.address.line1",
4996 "legal_entity.address.postal_code",
4997 "legal_entity.address.state",
4998 "legal_entity.dob.day",
4999 "legal_entity.dob.month",
5000 "legal_entity.dob.year",
5001 "legal_entity.first_name",
5002 "legal_entity.last_name",
5003 "legal_entity.ssn_last_4",
5004 "legal_entity.type",
5005 "tos_acceptance.date",
5006 "tos_acceptance.ip"
5007 ],
5008 "additional": [
5009 "legal_entity.personal_id_number",
5010 "legal_entity.verification.document"
5011 ]
5012 },
5013 "company": {
5014 "minimum": [
5015 "external_account",
5016 "legal_entity.address.city",
5017 "legal_entity.address.line1",
5018 "legal_entity.address.postal_code",
5019 "legal_entity.address.state",
5020 "legal_entity.business_name",
5021 "legal_entity.business_tax_id",
5022 "legal_entity.dob.day",
5023 "legal_entity.dob.month",
5024 "legal_entity.dob.year",
5025 "legal_entity.first_name",
5026 "legal_entity.last_name",
5027 "legal_entity.ssn_last_4",
5028 "legal_entity.type",
5029 "tos_acceptance.date",
5030 "tos_acceptance.ip"
5031 ],
5032 "additional": [
5033 "legal_entity.personal_id_number",
5034 "legal_entity.verification.document"
5035 ]
5036 }
5037 }
5038 }
5039 }
5040 }
5041}
5042```
5043
5044<a name="createBankAccount"/>
5045## Stripe.createBankAccount
5046When you create a new bank account, you must specify a managed account to create it on.
5047If the bank account's owner has no other external account in the bank account's currency, the new bank account will become the default for that currency. However, if the owner already has a bank account for that currency, the new account will only become the default if the default_for_currency parameter is set to true.
5048
5049| Field | Type | Description
5050|-------------------|------------|----------
5051| apiKey | credentials| The api key obtained from Stripe.
5052| accountId | String | The account ID obtained from Stripe.
5053| source | String | When adding a bank account to a customer, the parameter name is source. When adding to an account, the parameter name is external_account. The value can either be a token, like the ones returned by Stripe.js, or a dictionary containing a user’s bank account details (with the options shown below).
5054| externalAccount | String | When adding a bank account to a customer, the parameter name is source. When adding to an account, the parameter name is external_account. The value can either be a token, like the ones returned by Stripe.js, or a dictionary containing a user’s bank account details (with the options shown below).
5055| defaultForCurrency| String | If you set this to true (or if this is the first bank account being added in this currency) this bank account will become the default bank account for its currency.
5056| metadata | JSON | A set of key/value pairs that you can attach to an external account object. It can be useful for storing additional information about the external account in a structured format.
5057
5058#### Request example
5059```json
5060{
5061 "apiKey": "...",
5062 "accountId": "acct_1032D82eZvKYlo2C",
5063 "externalAccount": "btok_9I15a1JTOQZSQf",
5064}
5065```
5066#### Response example
5067```json
5068{
5069 "callback":"success",
5070 "contextWrites":{
5071 "#":{
5072 "to":{
5073 "id": "ba_18zR3H2eZvKYlo2CzLiGrogK",
5074 "object": "bank_account",
5075 "account": "acct_1032D82eZvKYlo2C",
5076 "account_holder_name": "Jane Austen",
5077 "account_holder_type": "individual",
5078 "bank_name": "STRIPE TEST BANK",
5079 "country": "US",
5080 "currency": "usd",
5081 "default_for_currency": false,
5082 "fingerprint": "1JWtPxqbdX5Gamtc",
5083 "last4": "6789",
5084 "metadata": {
5085 },
5086 "routing_number": "110000000",
5087 "status": "new"
5088 }
5089 }
5090 }
5091}
5092```
5093
5094<a name="getBankAccount"/>
5095## Stripe.getBankAccount
5096By default, you can see the 10 most recent bank accounts stored on a managed account directly on the object, but you can also retrieve details about a specific bank account stored on the Stripe account.
5097
5098| Field | Type | Description
5099|--------------|------------|----------
5100| apiKey | credentials| The api key obtained from Stripe.
5101| accountId | String | The account ID obtained from Stripe.
5102| bankAccountId| String | The bank account ID obtained from Stripe.
5103
5104#### Request example
5105```json
5106{
5107 "apiKey": "...",
5108 "accountId": "acct_1032D82eZvKYlo2C",
5109 "bankAccountId": "ba_18zR3H2eZvKYlo2CzLiGrogK"
5110}
5111```
5112#### Response example
5113```json
5114{
5115 "callback":"success",
5116 "contextWrites":{
5117 "#":{
5118 "to":{
5119 "id": "ba_18zR3H2eZvKYlo2CzLiGrogK",
5120 "object": "bank_account",
5121 "account": "acct_1032D82eZvKYlo2C",
5122 "account_holder_name": "Jane Austen",
5123 "account_holder_type": "individual",
5124 "bank_name": "STRIPE TEST BANK",
5125 "country": "US",
5126 "currency": "usd",
5127 "default_for_currency": false,
5128 "fingerprint": "1JWtPxqbdX5Gamtc",
5129 "last4": "6789",
5130 "metadata": {
5131 },
5132 "routing_number": "110000000",
5133 "status": "new"
5134 }
5135 }
5136 }
5137}
5138```
5139
5140<a name="updateBankAccount"/>
5141## Stripe.updateBankAccount
5142Updates the metadata of a bank account belonging to a managed account, and optionally sets it as the default for its currency. Other bank account details are not editable by design.
5143
5144| Field | Type | Description
5145|--------------|------------|----------
5146| apiKey | credentials| The api key obtained from Stripe.
5147| accountId | String | The account ID obtained from Stripe.
5148| bankAccountId| String | The ID of the bank account to be updated.
5149| metadata | JSON | A set of key/value pairs that you can attach to an external account object. It can be useful for storing additional information about the external account in a structured format.
5150
5151#### Request example
5152```json
5153{
5154 "apiKey": "...",
5155 "accountId": "acct_1032D82eZvKYlo2C",
5156 "bankAccountId": "ba_18zR3H2eZvKYlo2CzLiGrogK"
5157 "metadata": "{\"order_id\": \"6735\"}"
5158}
5159```
5160#### Response example
5161```json
5162{
5163 "callback":"success",
5164 "contextWrites":{
5165 "#":{
5166 "to": {
5167 "id": "ba_18zR3H2eZvKYlo2CzLiGrogK",
5168 "object": "bank_account",
5169 "account": "acct_1032D82eZvKYlo2C",
5170 "account_holder_name": "Jane Austen",
5171 "account_holder_type": "individual",
5172 "bank_name": "STRIPE TEST BANK",
5173 "country": "US",
5174 "currency": "usd",
5175 "default_for_currency": false,
5176 "fingerprint": "1JWtPxqbdX5Gamtc",
5177 "last4": "6789",
5178 "metadata": {
5179 "order_id": "6735"
5180 },
5181 "routing_number": "110000000",
5182 "status": "new"
5183 }
5184 }
5185 }
5186}
5187```
5188
5189<a name="deleteBankAccount"/>
5190## Stripe.deleteBankAccount
5191You can delete destination bank accounts from a managed account. If a bank account is the default external account for its currency, it can only be deleted if it is the only external account for that currency, and the currency is not the Stripe account's default currency. Otherwise, you must set another external account to be the default for the currency before deleting it.
5192
5193| Field | Type | Description
5194|--------------|------------|----------
5195| apiKey | credentials| The api key obtained from Stripe.
5196| accountId | String | The account ID obtained from Stripe.
5197| bankAccountId| String | The bank account ID obtained from Stripe.
5198
5199#### Request example
5200```json
5201{
5202 "apiKey": "...",
5203 "accountId": "acct_1032D82eZvKYlo2C",
5204 "bankAccountId": "ba_18zR3I2eZvKYlo2CsZ5WyBcI"
5205}
5206```
5207#### Response example
5208```json
5209{
5210 "callback":"success",
5211 "contextWrites":{
5212 "#":{
5213 "to": {
5214 "deleted": true,
5215 "id": "ba_18zR3I2eZvKYlo2CsZ5WyBcI"
5216 }
5217 }
5218 }
5219}
5220```
5221
5222<a name="getBankAccountList"/>
5223## Stripe.getBankAccountList
5224You can see a list of the bank accounts belonging to a managed account. Note that the 10 most recent external accounts are always available by default on the corresponding Stripe object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional bank accounts.
5225
5226| Field | Type | Description
5227|--------------|------------|----------
5228| apiKey | credentials| The api key obtained from Stripe.
5229| accountId | String | The account ID obtained from Stripe.
5230| endingBefore | String | 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.
5231| limit | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
5232| startingAfter| String | 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.
5233
5234#### Request example
5235```json
5236{
5237 "apiKey": "...",
5238 "accountId": "sk_test_BQokikJOvBiI2HlWgH4olfQ2",
5239}
5240```
5241#### Response example
5242```json
5243{
5244 "callback":"success",
5245 "contextWrites":{
5246 "#":{
5247 "to":{
5248 "object": "list",
5249 "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts",
5250 "has_more": false,
5251 "data": [
5252 {
5253 "id": "ba_18zR3I2eZvKYlo2CsZ5WyBcI",
5254 "object": "bank_account",
5255 "account": "acct_1032D82eZvKYlo2C",
5256 "account_holder_name": "Jane Austen",
5257 "account_holder_type": "individual",
5258 "bank_name": "STRIPE TEST BANK",
5259 "country": "US",
5260 "currency": "usd",
5261 "default_for_currency": false,
5262 "fingerprint": "1JWtPxqbdX5Gamtc",
5263 "last4": "6789",
5264 "metadata": {
5265 },
5266 "routing_number": "110000000",
5267 "status": "new"
5268 },
5269 {...},
5270 {...}
5271 ]
5272 }
5273 }
5274 }
5275}
5276```
5277
5278<a name="createCard"/>
5279## Stripe.createCard
5280If the account has no default destination card, then the new card will become the default. However, if the owner already has a default then it will not change. To change the default, you should set default_for_currency to true when creating a card for a managed account.
5281
5282| Field | Type | Description
5283|-------------------|------------|----------
5284| apiKey | credentials| The api key obtained from Stripe.
5285| accountId | String | The account ID obtained from Stripe.
5286| source | String | When adding a bank account to a customer, the parameter name is source. When adding to an account, the parameter name is external_account. The value can either be a token, like the ones returned by Stripe.js, or a dictionary containing a user’s bank account details (with the options shown below).
5287| externalAccount | String | When adding a bank account to a customer, the parameter name is source. When adding to an account, the parameter name is external_account. The value can either be a token, like the ones returned by Stripe.js, or a dictionary containing a user’s bank account details (with the options shown below).
5288| defaultForCurrency| String | If you set this to true (or if this is the first bank account being added in this currency) this bank account will become the default bank account for its currency.
5289| metadata | JSON | A set of key/value pairs that you can attach to an external account object. It can be useful for storing additional information about the external account in a structured format.
5290
5291#### Request example
5292```json
5293{
5294 "apiKey": "...",
5295 "accountId": "acct_1032D82eZvKYlo2C",
5296 "externalAccount": "tok_189fTS2eZvKYlo2CcYJIOGkr",
5297}
5298```
5299#### Response example
5300```json
5301{
5302 "callback":"success",
5303 "contextWrites":{
5304 "#":{
5305 "to":{
5306 "id": "card_18zR2T2eZvKYlo2Cn58EZoyn",
5307 "object": "card",
5308 "address_city": null,
5309 "address_country": null,
5310 "address_line1": null,
5311 "address_line1_check": null,
5312 "address_line2": null,
5313 "address_state": null,
5314 "address_zip": "226001",
5315 "address_zip_check": "unchecked",
5316 "brand": "Visa",
5317 "country": "US",
5318 "cvc_check": "unchecked",
5319 "dynamic_last4": null,
5320 "exp_month": 12,
5321 "exp_year": 2019,
5322 "funding": "credit",
5323 "last4": "4242",
5324 "metadata": {
5325 },
5326 "name": null,
5327 "tokenization_method": null,
5328 "account": "acct_1032D82eZvKYlo2C"
5329 }
5330 }
5331 }
5332}
5333```
5334
5335<a name="getCard"/>
5336## Stripe.getCard
5337You can always see the 10 most recent cards directly on a customer or recipient; this method lets you retrieve details about a specific card stored on the customer or recipient.
5338
5339| Field | Type | Description
5340|----------|------------|----------
5341| apiKey | credentials| The api key obtained from Stripe.
5342| accountId| String | The account ID obtained from Stripe.
5343| cardId | String | The card ID obtained from Stripe.
5344
5345#### Request example
5346```json
5347{
5348 "apiKey": "...",
5349 "accountId": "acct_1032D82eZvKYlo2C",
5350 "cardId": "card_18zR2T2eZvKYlo2Cn58EZoyn"
5351}
5352```
5353#### Response example
5354```json
5355{
5356 "callback":"success",
5357 "contextWrites":{
5358 "#":{
5359 "to": {
5360 "id": "card_18zR2T2eZvKYlo2Cn58EZoyn",
5361 "object": "card",
5362 "address_city": null,
5363 "address_country": null,
5364 "address_line1": null,
5365 "address_line1_check": null,
5366 "address_line2": null,
5367 "address_state": null,
5368 "address_zip": "226001",
5369 "address_zip_check": "unchecked",
5370 "brand": "Visa",
5371 "country": "US",
5372 "cvc_check": "unchecked",
5373 "dynamic_last4": null,
5374 "exp_month": 12,
5375 "exp_year": 2019,
5376 "funding": "credit",
5377 "last4": "4242",
5378 "metadata": {
5379 },
5380 "name": null,
5381 "tokenization_method": null,
5382 "account": "acct_1032D82eZvKYlo2C"
5383 }
5384 }
5385 }
5386}
5387```
5388
5389<a name="updateCard"/>
5390## Stripe.updateCard
5391If you need to update only some card details, like the billing address or expiration date, you can do so without having to re-enter the full card details. Stripe also works directly with card networks so that your customers can continue using your service without interruption.
5392When you update a card, Stripe will automatically validate the card.
5393
5394| Field | Type | Description
5395|-------------------|------------|----------
5396| apiKey | credentials| The api key obtained from Stripe.
5397| accountId | String | The account ID obtained from Stripe.
5398| cardId | String | The card ID obtained from Stripe.
5399| addressCity | String | City.
5400| addressCountry | String | Country.
5401| addressLine1 | String | Line 1.
5402| addressLine2 | String | Line 2.
5403| addressState | String | State.
5404| addressZip | String | State.
5405| defaultForCurrency| String | Only applicable on accounts (not customers or recipients). If set to true, this card will become the default external account for its currency..
5406| expMonth | String | Month.
5407| expYear | String | Year.
5408| metadata | String | 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 null and then saving.
5409| name | String | Name.
5410
5411#### Request example
5412```json
5413{
5414 "apiKey": "...",
5415 "accountId": "acct_1032D82eZvKYlo2C",
5416 "cardId": "card_18zR2T2eZvKYlo2Cn58EZoyn",
5417 "name": "Sophia Moore"
5418}
5419```
5420#### Response example
5421```json
5422{
5423 "callback":"success",
5424 "contextWrites":{
5425 "#":{
5426 "to": {
5427 "id": "card_18zR2T2eZvKYlo2Cn58EZoyn",
5428 "object": "card",
5429 "address_city": null,
5430 "address_country": null,
5431 "address_line1": null,
5432 "address_line1_check": null,
5433 "address_line2": null,
5434 "address_state": null,
5435 "address_zip": "226001",
5436 "address_zip_check": "unchecked",
5437 "brand": "Visa",
5438 "country": "US",
5439 "cvc_check": "unchecked",
5440 "dynamic_last4": null,
5441 "exp_month": 12,
5442 "exp_year": 2019,
5443 "funding": "credit",
5444 "last4": "4242",
5445 "metadata": {
5446 },
5447 "name": "Sophia Moore",
5448 "tokenization_method": null,
5449 "account": "acct_1032D82eZvKYlo2C"
5450 }
5451 }
5452 }
5453}
5454```
5455
5456<a name="deleteCard"/>
5457## Stripe.deleteCard
5458If a card's default_for_currency property is true, it can only be deleted if it is the only external account for its currency, and the currency is not the Stripe account's default currency. Otherwise, before deleting the card, you must set another external account to be the default for the currency.
5459
5460| Field | Type | Description
5461|----------|------------|----------
5462| apiKey | credentials| The api key obtained from Stripe.
5463| accountId| String | The account ID obtained from Stripe.
5464| cardId | String | The card ID obtained from Stripe.
5465
5466#### Request example
5467```json
5468{
5469 "apiKey": "...",
5470 "accountId": "acct_1032D82eZvKYlo2C",
5471 "cardId": "card_18zR2T2eZvKYlo2Cn58EZoyn"
5472}
5473```
5474#### Response example
5475```json
5476{
5477 "callback":"success",
5478 "contextWrites":{
5479 "#":{
5480 "to":{
5481 "deleted": true,
5482 "id": "card_18zR2T2eZvKYlo2Cn58EZoyn"
5483 }
5484 }
5485 }
5486}
5487```
5488
5489<a name="getCardList"/>
5490## Stripe.getCardList
5491You can see a list of the cards belonging to a managed account. Note that the 10 most recent external accounts are available on the account object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional cards.
5492
5493| Field | Type | Description
5494|--------------|------------|----------
5495| apiKey | credentials| The api key obtained from Stripe.
5496| accountId | String | The account ID obtained from Stripe.
5497| endingBefore | String | 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.
5498| limit | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
5499| startingAfter| String | 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.
5500
5501#### Request example
5502```json
5503{
5504 "apiKey": "...",
5505 "accountId": "acct_1032D82eZvKYlo2C",
5506}
5507```
5508#### Response example
5509```json
5510{
5511 "callback":"success",
5512 "contextWrites":{
5513 "#":{
5514 "to":{
5515 "object": "list",
5516 "url": "/v1/accounts/acct_1032D82eZvKYlo2C/external_accounts",
5517 "has_more": false,
5518 "data": [
5519 {
5520 "id": "card_18zR2T2eZvKYlo2Cn58EZoyn",
5521 "object": "card",
5522 "address_city": null,
5523 "address_country": null,
5524 "address_line1": null,
5525 "address_line1_check": null,
5526 "address_line2": null,
5527 "address_state": null,
5528 "address_zip": "226001",
5529 "address_zip_check": "unchecked",
5530 "brand": "Visa",
5531 "country": "US",
5532 "cvc_check": "unchecked",
5533 "dynamic_last4": null,
5534 "exp_month": 12,
5535 "exp_year": 2019,
5536 "funding": "credit",
5537 "last4": "4242",
5538 "metadata": {
5539 },
5540 "name": null,
5541 "tokenization_method": null,
5542 "account": "acct_1032D82eZvKYlo2C"
5543 },
5544 {...},
5545 {...}
5546 ]
5547 }
5548 }
5549 }
5550}
5551```
5552
5553<a name="createReceiver"/>
5554## Stripe.createReceiver
5555Method description
5556
5557| Field | Type | Description
5558|------------------|------------|----------
5559| apiKey | credentials| The api key obtained from Stripe.
5560| amount | String | The account ID obtained from Stripe.
5561| currency | String | Only USD currently supported
5562| email | String | 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.
5563| description | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
5564| metadata | String |
5565| refundMispayments| String |
5566
5567#### Request example
5568```json
5569{
5570 "apiKey": "...",
5571 "amount": "...",
5572 "currency": "usd",
5573 "email": "...",
5574 "description": "...",
5575 "metadata": "...",
5576 "refundMispayments": "..."
5577}
5578```
5579#### Response example
5580```json
5581{
5582 "callback":"success",
5583 "contextWrites":{
5584 "#":{
5585 "to":"..."
5586 }
5587 }
5588}
5589```
5590
5591<a name="getReceiver"/>
5592## Stripe.getReceiver
5593Method description
5594
5595| Field | Type | Description
5596|-----------|------------|----------
5597| apiKey | credentials| The api key obtained from Stripe.
5598| receiverId| String | Id of receiver to retrive.
5599
5600#### Request example
5601```json
5602{
5603 "apiKey": "...",
5604 "receiverId": "..."
5605}
5606```
5607#### Response example
5608```json
5609{
5610 "callback":"success",
5611 "contextWrites":{
5612 "#":{
5613 "to":"..."
5614 }
5615 }
5616}
5617```
5618
5619<a name="getReceiverList"/>
5620## Stripe.getReceiverList
5621Method description
5622
5623| Field | Type | Description
5624|-------|------------|----------
5625| apiKey| credentials| The api key obtained from Stripe.
5626
5627#### Request example
5628```json
5629{ "apiKey": "..."
5630}
5631```
5632#### Response example
5633```json
5634{
5635 "callback":"success",
5636 "contextWrites":{
5637 "#":{
5638 "to":"..."
5639 }
5640 }
5641}
5642```
5643
5644<a name="createOrder"/>
5645## Stripe.createOrder
5646Creates a new order object.
5647
5648| Field | Type | Description
5649|---------|------------|----------
5650| apiKey | credentials| The api key obtained from Stripe.
5651| currency| String | 3-letter ISO code representing the currency in which the order should be made. Stripe will validate that all entries in items match the currency specified here.
5652| coupon | String | A coupon code that represents a discount to be applied to this order. Must be one-time duration and in same currency as the order.
5653| customer| String | The ID of an existing customer to use for this order. If provided, the customer email and shipping address will be used to create the order. Subsequently, the customer will also be charged to pay the order. If email or shipping are also provided, they will override the values retrieved from the customer object.
5654| email | String | The email address of the customer placing the order.
5655| items | JSON | List of items constituting the order.
5656| metadata| JSON | A set of key/value pairs that you can attach to an order object. It can be useful for storing additional information about the order in a structured format.
5657| shipping| JSON | Shipping address for the order. Required if any of the SKUs are for products that have shippable set to true.
5658
5659#### Request example
5660```json
5661{
5662 "apiKey": "...",
5663 "currency": "usd",
5664 "email": "anthony.anderson@example.com",
5665 "items": "[{\"type\": \"sku\", \"parent\": \"sku_9BtKAR1ZXD42en\"}]",
5666}
5667```
5668#### Response example
5669```json
5670{
5671 "callback":"success",
5672 "contextWrites":{
5673 "#":{
5674 "to": {
5675 "id": "or_18tVaP2eZvKYlo2CP5mgybEM",
5676 "object": "order",
5677 "amount": 3084,
5678 "amount_returned": 3084,
5679 "application": null,
5680 "application_fee": null,
5681 "charge": "ch_18z3WS2eZvKYlo2ChBcCbkN5",
5682 "created": 1473829529,
5683 "currency": "usd",
5684 "customer": null,
5685 "email": "jenny@example.com",
5686 "items": [
5687 {
5688 "object": "order_item",
5689 "amount": 3084,
5690 "currency": "usd",
5691 "description": "T-shirt",
5692 "parent": "sku_98dMiVopxu0m3r",
5693 "quantity": 2,
5694 "type": "sku"
5695 },
5696 {
5697 "object": "order_item",
5698 "amount": 0,
5699 "currency": "usd",
5700 "description": "Taxes (included)",
5701 "parent": null,
5702 "quantity": null,
5703 "type": "tax"
5704 },
5705 {
5706 "object": "order_item",
5707 "amount": 0,
5708 "currency": "usd",
5709 "description": "Free shipping",
5710 "parent": "ship_free-shipping",
5711 "quantity": null,
5712 "type": "shipping"
5713 }
5714 ],
5715 "livemode": false,
5716 "metadata": {
5717 },
5718 "returns": {
5719 "object": "list",
5720 "data": [
5721 {
5722 "id": "orret_18z4Ju2eZvKYlo2CqDgoOMW5",
5723 "object": "order_return",
5724 "amount": 3084,
5725 "created": 1475154686,
5726 "currency": "usd",
5727 "items": [
5728 {
5729 "object": "order_item",
5730 "amount": 3084,
5731 "currency": "usd",
5732 "description": "T-shirt",
5733 "parent": "sku_98dMiVopxu0m3r",
5734 "quantity": 2,
5735 "type": "sku"
5736 },
5737 {
5738 "object": "order_item",
5739 "amount": 0,
5740 "currency": "usd",
5741 "description": "Taxes (included)",
5742 "parent": null,
5743 "quantity": null,
5744 "type": "tax"
5745 },
5746 {
5747 "object": "order_item",
5748 "amount": 0,
5749 "currency": "usd",
5750 "description": "Free shipping",
5751 "parent": "ship_free-shipping",
5752 "quantity": null,
5753 "type": "shipping"
5754 }
5755 ],
5756 "livemode": false,
5757 "order": "or_18tVaP2eZvKYlo2CP5mgybEM",
5758 "refund": "re_18z4Ju2eZvKYlo2CGOBWgZtx"
5759 }
5760 ],
5761 "has_more": false,
5762 "total_count": 1,
5763 "url": "/v1/order_returns?order=or_18tVaP2eZvKYlo2CP5mgybEM"
5764 },
5765 "selected_shipping_method": "ship_free-shipping",
5766 "shipping": {
5767 "address": {
5768 "city": "Anytown",
5769 "country": "US",
5770 "line1": "1234 Main Street",
5771 "line2": null,
5772 "postal_code": "123456",
5773 "state": null
5774 },
5775 "carrier": null,
5776 "name": "Jenny Rosen",
5777 "phone": null,
5778 "tracking_number": null
5779 },
5780 "shipping_methods": [
5781 {
5782 "id": "ship_free-shipping",
5783 "amount": 0,
5784 "currency": "usd",
5785 "delivery_estimate": null,
5786 "description": "Free shipping"
5787 }
5788 ],
5789 "status": "canceled",
5790 "status_transitions": null,
5791 "updated": 1475154686
5792 }
5793 }
5794 }
5795}
5796```
5797
5798<a name="getOrder"/>
5799## Stripe.getOrder
5800Retrieves the details of an existing order. Supply the unique order ID from either an order creation request or the order list, and Stripe will return the corresponding order information.
5801
5802| Field | Type | Description
5803|--------|------------|----------
5804| apiKey | credentials| The api key obtained from Stripe.
5805| orderId| String | Id of receiver to retrive.
5806
5807#### Request example
5808```json
5809{
5810 "apiKey": "...",
5811 "orderId": "or_18tVaP2eZvKYlo2CP5mgybEM"
5812}
5813```
5814#### Response example
5815```json
5816{
5817 "callback":"success",
5818 "contextWrites":{
5819 "#":{
5820 "to": {
5821 "id": "or_18tVaP2eZvKYlo2CP5mgybEM",
5822 "object": "order",
5823 "amount": 3084,
5824 "amount_returned": 3084,
5825 "application": null,
5826 "application_fee": null,
5827 "charge": "ch_18z3WS2eZvKYlo2ChBcCbkN5",
5828 "created": 1473829529,
5829 "currency": "usd",
5830 "customer": null,
5831 "email": "jenny@example.com",
5832 "items": [
5833 {
5834 "object": "order_item",
5835 "amount": 3084,
5836 "currency": "usd",
5837 "description": "T-shirt",
5838 "parent": "sku_98dMiVopxu0m3r",
5839 "quantity": 2,
5840 "type": "sku"
5841 },
5842 {
5843 "object": "order_item",
5844 "amount": 0,
5845 "currency": "usd",
5846 "description": "Taxes (included)",
5847 "parent": null,
5848 "quantity": null,
5849 "type": "tax"
5850 },
5851 {
5852 "object": "order_item",
5853 "amount": 0,
5854 "currency": "usd",
5855 "description": "Free shipping",
5856 "parent": "ship_free-shipping",
5857 "quantity": null,
5858 "type": "shipping"
5859 }
5860 ],
5861 "livemode": false,
5862 "metadata": {
5863 },
5864 "returns": {
5865 "object": "list",
5866 "data": [
5867 {
5868 "id": "orret_18z4Ju2eZvKYlo2CqDgoOMW5",
5869 "object": "order_return",
5870 "amount": 3084,
5871 "created": 1475154686,
5872 "currency": "usd",
5873 "items": [
5874 {
5875 "object": "order_item",
5876 "amount": 3084,
5877 "currency": "usd",
5878 "description": "T-shirt",
5879 "parent": "sku_98dMiVopxu0m3r",
5880 "quantity": 2,
5881 "type": "sku"
5882 },
5883 {
5884 "object": "order_item",
5885 "amount": 0,
5886 "currency": "usd",
5887 "description": "Taxes (included)",
5888 "parent": null,
5889 "quantity": null,
5890 "type": "tax"
5891 },
5892 {
5893 "object": "order_item",
5894 "amount": 0,
5895 "currency": "usd",
5896 "description": "Free shipping",
5897 "parent": "ship_free-shipping",
5898 "quantity": null,
5899 "type": "shipping"
5900 }
5901 ],
5902 "livemode": false,
5903 "order": "or_18tVaP2eZvKYlo2CP5mgybEM",
5904 "refund": "re_18z4Ju2eZvKYlo2CGOBWgZtx"
5905 }
5906 ],
5907 "has_more": false,
5908 "total_count": 1,
5909 "url": "/v1/order_returns?order=or_18tVaP2eZvKYlo2CP5mgybEM"
5910 },
5911 "selected_shipping_method": "ship_free-shipping",
5912 "shipping": {
5913 "address": {
5914 "city": "Anytown",
5915 "country": "US",
5916 "line1": "1234 Main Street",
5917 "line2": null,
5918 "postal_code": "123456",
5919 "state": null
5920 },
5921 "carrier": null,
5922 "name": "Jenny Rosen",
5923 "phone": null,
5924 "tracking_number": null
5925 },
5926 "shipping_methods": [
5927 {
5928 "id": "ship_free-shipping",
5929 "amount": 0,
5930 "currency": "usd",
5931 "delivery_estimate": null,
5932 "description": "Free shipping"
5933 }
5934 ],
5935 "status": "canceled",
5936 "status_transitions": null,
5937 "updated": 1475154686
5938 }
5939 }
5940 }
5941}
5942```
5943
5944<a name="updateOrder"/>
5945## Stripe.updateOrder
5946Updates the specific order by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts only the metadata, and status as arguments.
5947
5948| Field | Type | Description
5949|---------|------------|----------
5950| apiKey | credentials| The api key obtained from Stripe.
5951| orderId | credentials| Id of order to update.
5952| coupon | String | A coupon code that represents a discount to be applied to this order. Must be one-time duration and in same currency as the order.
5953| metadata| JSON | A set of key/value pairs that you can attach to an order object. It can be useful for storing additional information about the order in a structured format.
5954| shipping| JSON | Shipping address for the order. Required if any of the SKUs are for products that have shippable set to true.
5955| status | credentials| Current order status. One of `created`, `paid`, `canceled`, `fulfilled`, or `returned`.
5956
5957#### Request example
5958```json
5959{
5960 "apiKey": "...",
5961 "orderId": "or_18tVaP2eZvKYlo2CP5mgybEM",
5962 "metadata": "...",
5963}
5964```
5965#### Response example
5966```json
5967{
5968 "callback":"success",
5969 "contextWrites":{
5970 "#":{
5971 "to": {
5972 "id": "or_18tVaP2eZvKYlo2CP5mgybEM",
5973 "object": "order",
5974 "amount": 3084,
5975 "amount_returned": 3084,
5976 "application": null,
5977 "application_fee": null,
5978 "charge": "ch_18z3WS2eZvKYlo2ChBcCbkN5",
5979 "created": 1473829529,
5980 "currency": "usd",
5981 "customer": null,
5982 "email": "jenny@example.com",
5983 "items": [
5984 {
5985 "object": "order_item",
5986 "amount": 3084,
5987 "currency": "usd",
5988 "description": "T-shirt",
5989 "parent": "sku_98dMiVopxu0m3r",
5990 "quantity": 2,
5991 "type": "sku"
5992 },
5993 {
5994 "object": "order_item",
5995 "amount": 0,
5996 "currency": "usd",
5997 "description": "Taxes (included)",
5998 "parent": null,
5999 "quantity": null,
6000 "type": "tax"
6001 },
6002 {
6003 "object": "order_item",
6004 "amount": 0,
6005 "currency": "usd",
6006 "description": "Free shipping",
6007 "parent": "ship_free-shipping",
6008 "quantity": null,
6009 "type": "shipping"
6010 }
6011 ],
6012 "livemode": false,
6013 "metadata": {
6014 "order_id": "6735"
6015 },
6016 "returns": {
6017 "object": "list",
6018 "data": [
6019 {
6020 "id": "orret_18z4Ju2eZvKYlo2CqDgoOMW5",
6021 "object": "order_return",
6022 "amount": 3084,
6023 "created": 1475154686,
6024 "currency": "usd",
6025 "items": [
6026 {
6027 "object": "order_item",
6028 "amount": 3084,
6029 "currency": "usd",
6030 "description": "T-shirt",
6031 "parent": "sku_98dMiVopxu0m3r",
6032 "quantity": 2,
6033 "type": "sku"
6034 },
6035 {
6036 "object": "order_item",
6037 "amount": 0,
6038 "currency": "usd",
6039 "description": "Taxes (included)",
6040 "parent": null,
6041 "quantity": null,
6042 "type": "tax"
6043 },
6044 {
6045 "object": "order_item",
6046 "amount": 0,
6047 "currency": "usd",
6048 "description": "Free shipping",
6049 "parent": "ship_free-shipping",
6050 "quantity": null,
6051 "type": "shipping"
6052 }
6053 ],
6054 "livemode": false,
6055 "order": "or_18tVaP2eZvKYlo2CP5mgybEM",
6056 "refund": "re_18z4Ju2eZvKYlo2CGOBWgZtx"
6057 }
6058 ],
6059 "has_more": false,
6060 "total_count": 1,
6061 "url": "/v1/order_returns?order=or_18tVaP2eZvKYlo2CP5mgybEM"
6062 },
6063 "selected_shipping_method": "ship_free-shipping",
6064 "shipping": {
6065 "address": {
6066 "city": "Anytown",
6067 "country": "US",
6068 "line1": "1234 Main Street",
6069 "line2": null,
6070 "postal_code": "123456",
6071 "state": null
6072 },
6073 "carrier": null,
6074 "name": "Jenny Rosen",
6075 "phone": null,
6076 "tracking_number": null
6077 },
6078 "shipping_methods": [
6079 {
6080 "id": "ship_free-shipping",
6081 "amount": 0,
6082 "currency": "usd",
6083 "delivery_estimate": null,
6084 "description": "Free shipping"
6085 }
6086 ],
6087 "status": "canceled",
6088 "status_transitions": null,
6089 "updated": 1475154686
6090 }
6091 }
6092 }
6093}
6094```
6095
6096<a name="payOrder"/>
6097## Stripe.payOrder
6098Pay an order by providing a source to create a payment.
6099
6100| Field | Type | Description
6101|---------|------------|----------
6102| apiKey | credentials| The api key obtained from Stripe.
6103| orderId | String | The ID of an order to pay.
6104| customer| String | The ID of an existing customer that will be charged in this request.
6105| source | String | A payment source to be charged, such as a credit card. If you also pass a customer ID, the source must be the ID of a source belonging to the customer. Otherwise, if you do not pass a customer ID, the source you provide must either be a token, like the ones returned by Stripe.js, or a object containing a user's credit card details, with the options described below. Although not all information is required, the extra info helps prevent fraud.
6106| metadata| JSON | A set of key/value pairs that you can attach to an order object. It can be useful for storing additional information about the order in a structured format.
6107| email | String | The email address of the customer placing the order. If a customer is specified, that customer's email address will be used.
6108
6109#### Request example
6110```json
6111{
6112 "apiKey": "...",
6113 "orderId": "tok_189fTS2eZvKYlo2CcYJIOGkr",
6114}
6115```
6116#### Response example
6117```json
6118{
6119 "callback":"success",
6120 "contextWrites":{
6121 "#":{
6122 "to":{
6123 "id": "or_18tVaP2eZvKYlo2CP5mgybEM",
6124 "object": "order",
6125 "amount": 3084,
6126 "amount_returned": 3084,
6127 "application": null,
6128 "application_fee": null,
6129 "charge": "ch_18zRBY2eZvKYlo2C2g0wvnvx",
6130 "created": 1473829529,
6131 "currency": "usd",
6132 "customer": null,
6133 "email": "jenny@example.com",
6134 "items": [
6135 {
6136 "object": "order_item",
6137 "amount": 3084,
6138 "currency": "usd",
6139 "description": "T-shirt",
6140 "parent": "sku_98dMiVopxu0m3r",
6141 "quantity": 2,
6142 "type": "sku"
6143 },
6144 {
6145 "object": "order_item",
6146 "amount": 0,
6147 "currency": "usd",
6148 "description": "Taxes (included)",
6149 "parent": null,
6150 "quantity": null,
6151 "type": "tax"
6152 },
6153 {
6154 "object": "order_item",
6155 "amount": 0,
6156 "currency": "usd",
6157 "description": "Free shipping",
6158 "parent": "ship_free-shipping",
6159 "quantity": null,
6160 "type": "shipping"
6161 }
6162 ],
6163 "livemode": false,
6164 "metadata": {
6165 },
6166 "returns": {
6167 "object": "list",
6168 "data": [
6169 {
6170 "id": "orret_18z4Ju2eZvKYlo2CqDgoOMW5",
6171 "object": "order_return",
6172 "amount": 3084,
6173 "created": 1475154686,
6174 "currency": "usd",
6175 "items": [
6176 {
6177 "object": "order_item",
6178 "amount": 3084,
6179 "currency": "usd",
6180 "description": "T-shirt",
6181 "parent": "sku_98dMiVopxu0m3r",
6182 "quantity": 2,
6183 "type": "sku"
6184 },
6185 {
6186 "object": "order_item",
6187 "amount": 0,
6188 "currency": "usd",
6189 "description": "Taxes (included)",
6190 "parent": null,
6191 "quantity": null,
6192 "type": "tax"
6193 },
6194 {
6195 "object": "order_item",
6196 "amount": 0,
6197 "currency": "usd",
6198 "description": "Free shipping",
6199 "parent": "ship_free-shipping",
6200 "quantity": null,
6201 "type": "shipping"
6202 }
6203 ],
6204 "livemode": false,
6205 "order": "or_18tVaP2eZvKYlo2CP5mgybEM",
6206 "refund": "re_18z4Ju2eZvKYlo2CGOBWgZtx"
6207 }
6208 ],
6209 "has_more": false,
6210 "total_count": 1,
6211 "url": "/v1/order_returns?order=or_18tVaP2eZvKYlo2CP5mgybEM"
6212 },
6213 "selected_shipping_method": "ship_free-shipping",
6214 "shipping": {
6215 "address": {
6216 "city": "Anytown",
6217 "country": "US",
6218 "line1": "1234 Main Street",
6219 "line2": null,
6220 "postal_code": "123456",
6221 "state": null
6222 },
6223 "carrier": null,
6224 "name": "Jenny Rosen",
6225 "phone": null,
6226 "tracking_number": null
6227 },
6228 "shipping_methods": [
6229 {
6230 "id": "ship_free-shipping",
6231 "amount": 0,
6232 "currency": "usd",
6233 "delivery_estimate": null,
6234 "description": "Free shipping"
6235 }
6236 ],
6237 "status": "paid",
6238 "status_transitions": null,
6239 "updated": 1475154686
6240 }
6241 }
6242 }
6243}
6244```
6245
6246<a name="getOrderList"/>
6247## Stripe.getOrderList
6248Returns a list of your orders. The orders are returned sorted by creation date, with the most recently created orders appearing first.
6249
6250| Field | Type | Description
6251|------------------|------------|----------
6252| apiKey | credentials| The api key obtained from Stripe.
6253| created | String | A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:
6254| customer | String | Only return orders for the given customer.
6255| ids | String | Only return orders with the given IDs.
6256| status | String | Only return orders that have the given status. One of `created`, `paid`, `fulfilled`, or `refunded`.
6257| statusTransitions| String | Filter orders based on when they were paid, fulfilled, canceled, or returned.
6258| upstreamIds | String | Only return orders with the given upstream order IDs.
6259
6260#### Request example
6261```json
6262{
6263 "apiKey": "...",
6264}
6265```
6266#### Response example
6267```json
6268{
6269 "callback":"success",
6270 "contextWrites":{
6271 "#":{
6272 "to": {
6273 "object": "list",
6274 "url": "/v1/orders",
6275 "has_more": false,
6276 "data": [
6277 {
6278 "id": "or_18tVaP2eZvKYlo2CP5mgybEM",
6279 "object": "order",
6280 "amount": 3084,
6281 "amount_returned": 3084,
6282 "application": null,
6283 "application_fee": null,
6284 "charge": "ch_18z3WS2eZvKYlo2ChBcCbkN5",
6285 "created": 1473829529,
6286 "currency": "usd",
6287 "customer": null,
6288 "email": "jenny@example.com",
6289 "items": [
6290 {
6291 "object": "order_item",
6292 "amount": 3084,
6293 "currency": "usd",
6294 "description": "T-shirt",
6295 "parent": "sku_98dMiVopxu0m3r",
6296 "quantity": 2,
6297 "type": "sku"
6298 },
6299 {
6300 "object": "order_item",
6301 "amount": 0,
6302 "currency": "usd",
6303 "description": "Taxes (included)",
6304 "parent": null,
6305 "quantity": null,
6306 "type": "tax"
6307 },
6308 {
6309 "object": "order_item",
6310 "amount": 0,
6311 "currency": "usd",
6312 "description": "Free shipping",
6313 "parent": "ship_free-shipping",
6314 "quantity": null,
6315 "type": "shipping"
6316 }
6317 ],
6318 "livemode": false,
6319 "metadata": {
6320 },
6321 "returns": {
6322 "object": "list",
6323 "data": [
6324 {
6325 "id": "orret_18z4Ju2eZvKYlo2CqDgoOMW5",
6326 "object": "order_return",
6327 "amount": 3084,
6328 "created": 1475154686,
6329 "currency": "usd",
6330 "items": [
6331 {
6332 "object": "order_item",
6333 "amount": 3084,
6334 "currency": "usd",
6335 "description": "T-shirt",
6336 "parent": "sku_98dMiVopxu0m3r",
6337 "quantity": 2,
6338 "type": "sku"
6339 },
6340 {
6341 "object": "order_item",
6342 "amount": 0,
6343 "currency": "usd",
6344 "description": "Taxes (included)",
6345 "parent": null,
6346 "quantity": null,
6347 "type": "tax"
6348 },
6349 {
6350 "object": "order_item",
6351 "amount": 0,
6352 "currency": "usd",
6353 "description": "Free shipping",
6354 "parent": "ship_free-shipping",
6355 "quantity": null,
6356 "type": "shipping"
6357 }
6358 ],
6359 "livemode": false,
6360 "order": "or_18tVaP2eZvKYlo2CP5mgybEM",
6361 "refund": "re_18z4Ju2eZvKYlo2CGOBWgZtx"
6362 }
6363 ],
6364 "has_more": false,
6365 "total_count": 1,
6366 "url": "/v1/order_returns?order=or_18tVaP2eZvKYlo2CP5mgybEM"
6367 },
6368 "selected_shipping_method": "ship_free-shipping",
6369 "shipping": {
6370 "address": {
6371 "city": "Anytown",
6372 "country": "US",
6373 "line1": "1234 Main Street",
6374 "line2": null,
6375 "postal_code": "123456",
6376 "state": null
6377 },
6378 "carrier": null,
6379 "name": "Jenny Rosen",
6380 "phone": null,
6381 "tracking_number": null
6382 },
6383 "shipping_methods": [
6384 {
6385 "id": "ship_free-shipping",
6386 "amount": 0,
6387 "currency": "usd",
6388 "delivery_estimate": null,
6389 "description": "Free shipping"
6390 }
6391 ],
6392 "status": "canceled",
6393 "status_transitions": null,
6394 "updated": 1475154686
6395 },
6396 {...},
6397 {...}
6398 ]
6399 }
6400 }
6401 }
6402}
6403```
6404
6405<a name="returnOrder"/>
6406## Stripe.returnOrder
6407Return all or part of an order. The order must have a status of paid or fulfilled before it can be returned. Once all items have been returned, the order will become canceled or returned depending on which status the order started in.
6408
6409| Field | Type | Description
6410|--------|------------|----------
6411| apiKey | credentials| The api key obtained from Stripe.
6412| orderId| JSON | Order id.
6413| items | JSON | List of items to return.
6414
6415#### Request example
6416```json
6417{
6418 "apiKey": "...",
6419 "orderId": "...",
6420 "items": [{"type": "sku", "parent": "sku_9BtKAR1ZXD42en"}]
6421}
6422```
6423#### Response example
6424```json
6425{
6426 "callback":"success",
6427 "contextWrites":{
6428 "#":{
6429 "to": {
6430 "id": "orret_18z4Ju2eZvKYlo2CqDgoOMW5",
6431 "object": "order_return",
6432 "amount": 3084,
6433 "created": 1475154686,
6434 "currency": "usd",
6435 "items": [
6436 {
6437 "object": "order_item",
6438 "amount": 3084,
6439 "currency": "usd",
6440 "description": "T-shirt",
6441 "parent": "sku_98dMiVopxu0m3r",
6442 "quantity": 2,
6443 "type": "sku"
6444 },
6445 {
6446 "object": "order_item",
6447 "amount": 0,
6448 "currency": "usd",
6449 "description": "Taxes (included)",
6450 "parent": null,
6451 "quantity": null,
6452 "type": "tax"
6453 },
6454 {
6455 "object": "order_item",
6456 "amount": 0,
6457 "currency": "usd",
6458 "description": "Free shipping",
6459 "parent": "ship_free-shipping",
6460 "quantity": null,
6461 "type": "shipping"
6462 }
6463 ],
6464 "livemode": false,
6465 "order": "or_18tVaP2eZvKYlo2CP5mgybEM",
6466 "refund": "re_18z4Ju2eZvKYlo2CGOBWgZtx"
6467 }
6468 }
6469 }
6470}
6471```
6472
6473<a name="getOrderReturn"/>
6474## Stripe.getOrderReturn
6475Returns a list of your order returns. The returns are returned sorted by creation date, with the most recently created return appearing first.
6476
6477| Field | Type | Description
6478|--------|------------|----------
6479| apiKey | credentials| The api key obtained from Stripe.
6480| orderId| JSON | The identifier of the order return to be retrieved.
6481
6482#### Request example
6483```json
6484{
6485 "apiKey": "...",
6486 "orderId": "orret_18z4Ju2eZvKYlo2CqDgoOMW5"
6487}
6488```
6489#### Response example
6490```json
6491{
6492 "callback":"success",
6493 "contextWrites":{
6494 "#":{
6495 "to": {
6496 "id": "orret_18z4Ju2eZvKYlo2CqDgoOMW5",
6497 "object": "order_return",
6498 "amount": 3084,
6499 "created": 1475154686,
6500 "currency": "usd",
6501 "items": [
6502 {
6503 "object": "order_item",
6504 "amount": 3084,
6505 "currency": "usd",
6506 "description": "T-shirt",
6507 "parent": "sku_98dMiVopxu0m3r",
6508 "quantity": 2,
6509 "type": "sku"
6510 },
6511 {
6512 "object": "order_item",
6513 "amount": 0,
6514 "currency": "usd",
6515 "description": "Taxes (included)",
6516 "parent": null,
6517 "quantity": null,
6518 "type": "tax"
6519 },
6520 {
6521 "object": "order_item",
6522 "amount": 0,
6523 "currency": "usd",
6524 "description": "Free shipping",
6525 "parent": "ship_free-shipping",
6526 "quantity": null,
6527 "type": "shipping"
6528 }
6529 ],
6530 "livemode": false,
6531 "order": "or_18tVaP2eZvKYlo2CP5mgybEM",
6532 "refund": "re_18z4Ju2eZvKYlo2CGOBWgZtx"
6533 }
6534 }
6535 }
6536}
6537```
6538
6539<a name="getOrderReturnList"/>
6540## Stripe.getOrderReturnList
6541Returns a list of your order returns. The returns are returned sorted by creation date, with the most recently created return appearing first.
6542
6543| Field | Type | Description
6544|--------|------------|----------
6545| apiKey | credentials| The api key obtained from Stripe.
6546| created| String | A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:
6547
6548#### Request example
6549```json
6550{
6551 "apiKey": "...",
6552}
6553```
6554#### Response example
6555```json
6556{
6557 "callback":"success",
6558 "contextWrites":{
6559 "#":{
6560 "to": {
6561 "object": "list",
6562 "url": "/v1/order_returns",
6563 "has_more": false,
6564 "data": [
6565 {
6566 "id": "orret_18z4Ju2eZvKYlo2CqDgoOMW5",
6567 "object": "sku",
6568 "active": true,
6569 "attributes": {
6570 "color": "Cyan",
6571 "gender": "Unisex",
6572 "size": "Medium"
6573 },
6574 "created": 1473829395,
6575 "currency": "usd",
6576 "image": null,
6577 "inventory": {
6578 "quantity": 500,
6579 "type": "finite",
6580 "value": null
6581 },
6582 "livemode": false,
6583 "metadata": {
6584 },
6585 "package_dimensions": null,
6586 "price": 1500,
6587 "product": "prod_9I00GcePCVmLik",
6588 "updated": 1473829395
6589 },
6590 {...},
6591 {...}
6592 ]
6593 }
6594 }
6595 }
6596}
6597```
6598
6599<a name="createProduct"/>
6600## Stripe.createProduct
6601Creates a new product object.
6602
6603| Field | Type | Description
6604|------------------|------------|----------
6605| apiKey | credentials| The api key obtained from Stripe.
6606| name | String | The product’s name, meant to be displayable to the customer.
6607| active | String | Whether or not the product is currently available for purchase. Defaults to `true`.
6608| attributes | JSON | A list of up to 5 alphanumeric attributes that each SKU can provide values for (e.g. `["color", "size"]`).
6609| caption | String | A short one-line description of the product, meant to be displayable to the customer.
6610| deactivateOn | JSON | An array of Connect application names or identifiers that should not be able to order the SKUs for this product.
6611| description | String | The product’s description, meant to be displayable to the customer.
6612| images | JSON | A list of up to 8 URLs of images for this product, meant to be displayable to the customer.
6613| metadata | JSON | A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format.
6614| packageDimensions| String | The dimensions of this product for shipping purposes. A SKU associated with this product can override this value by having its own package_dimensions.
6615| shippable | String | Whether this product is shipped (i.e. physical goods). Defaults to true.
6616| url | String | A URL of a publicly-accessible webpage for this product.
6617
6618#### Request example
6619```json
6620{
6621 "apiKey": "...",
6622 "name": "T-shirt",
6623 "attributes": ["size", "gender"],
6624 "caption": "...",
6625 "deactivateOn": "...",
6626 "description": "Comfortable cotton t-shirt",
6627 "images": "...",
6628 "metadata": "...",
6629 "packageDimensions": "...",
6630 "shippable": "...",
6631 "url": "..."
6632}
6633```
6634#### Response example
6635```json
6636{
6637 "callback":"success",
6638 "contextWrites":{
6639 "#":{
6640 "to":{
6641 "id": "prod_9I00GcePCVmLik",
6642 "object": "product",
6643 "active": true,
6644 "attributes": [],
6645 "caption": null,
6646 "created": 1475238070,
6647 "deactivate_on": [],
6648 "description": "Test",
6649 "images": [],
6650 "livemode": false,
6651 "metadata": {
6652 },
6653 "name": "test",
6654 "package_dimensions": null,
6655 "shippable": true,
6656 "skus": {
6657 "object": "list",
6658 "data": [],
6659 "has_more": false,
6660 "total_count": 0,
6661 "url": "/v1/skus?product=prod_9I00GcePCVmLik\u0026active=true"
6662 },
6663 "updated": 1475238070,
6664 "url": null
6665 }
6666 }
6667 }
6668}
6669```
6670
6671<a name="getProduct"/>
6672## Stripe.getProduct
6673Store representations of products you sell in product objects, used in conjunction with SKUs. Products may be physical goods, to be shipped, or digital.
6674
6675| Field | Type | Description
6676|----------|------------|----------
6677| apiKey | credentials| The api key obtained from Stripe.
6678| productId| String | The identifier of the product to be retrieved.
6679
6680#### Request example
6681```json
6682{
6683 "apiKey": "...",
6684 "productId": "prod_9I00GcePCVmLik"
6685}
6686```
6687#### Response example
6688```json
6689{
6690 "callback":"success",
6691 "contextWrites":{
6692 "#":{
6693 "to": {
6694 "id": "prod_9I00GcePCVmLik",
6695 "object": "product",
6696 "active": true,
6697 "attributes": [],
6698 "caption": null,
6699 "created": 1475238070,
6700 "deactivate_on": [ ],
6701 "description": "Test",
6702 "images": [],
6703 "livemode": false,
6704 "metadata": {
6705 },
6706 "name": "test",
6707 "package_dimensions": null,
6708 "shippable": true,
6709 "skus": {
6710 "object": "list",
6711 "data": [],
6712 "has_more": false,
6713 "total_count": 0,
6714 "url": "/v1/skus?product=prod_9I00GcePCVmLik\u0026active=true"
6715 },
6716 "updated": 1475238070,
6717 "url": null
6718 }
6719 }
6720 }
6721}
6722```
6723
6724<a name="updateProduct"/>
6725## Stripe.updateProduct
6726Updates the specific product by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
6727Note that a product's attributes are not editable. Instead, you would need to deactivate the existing product and create a new one with the new attribute values.
6728
6729| Field | Type | Description
6730|------------------|------------|----------
6731| apiKey | credentials| The api key obtained from Stripe.
6732| productId | String | The id of product to update.
6733| name | String | The product’s name, meant to be displayable to the customer.
6734| active | String | Whether or not the product is currently available for purchase. Defaults to `true`.
6735| attributes | JSON | A list of up to 5 alphanumeric attributes that each SKU can provide values for (e.g. `["color", "size"]`).
6736| caption | String | A short one-line description of the product, meant to be displayable to the customer.
6737| deactivateOn | JSON | An array of Connect application names or identifiers that should not be able to order the SKUs for this product.
6738| description | String | The product’s description, meant to be displayable to the customer.
6739| images | JSON | A list of up to 8 URLs of images for this product, meant to be displayable to the customer.
6740| metadata | JSON | A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format.
6741| packageDimensions| String | The dimensions of this product for shipping purposes. A SKU associated with this product can override this value by having its own package_dimensions.
6742| shippable | String | Whether this product is shipped (i.e. physical goods). Defaults to true.
6743| url | String | A URL of a publicly-accessible webpage for this product.
6744
6745#### Request example
6746```json
6747{
6748 "apiKey": "...",
6749 "productId": "pr_18zQ0o2eZvKYlo2CxWcZi2sj",
6750 "name": "Test",
6751}
6752```
6753#### Response example
6754```json
6755{
6756 "callback":"success",
6757 "contextWrites":{
6758 "#":{
6759 "to": {
6760 "id": "prod_9I00GcePCVmLik",
6761 "object": "product",
6762 "active": true,
6763 "attributes": [],
6764 "caption": null,
6765 "created": 1475238070,
6766 "deactivate_on": [ ],
6767 "description": "Test",
6768 "images": [],
6769 "livemode": false,
6770 "metadata": {
6771 },
6772 "name": "test",
6773 "package_dimensions": null,
6774 "shippable": true,
6775 "skus": {
6776 "object": "list",
6777 "data": [],
6778 "has_more": false,
6779 "total_count": 0,
6780 "url": "/v1/skus?product=prod_9I00GcePCVmLik\u0026active=true"
6781 },
6782 "updated": 1475238070,
6783 "url": null
6784 }
6785 }
6786 }
6787}
6788
6789<a name="getProductList"/>
6790## Stripe.getProductList
6791Returns a list of your products. The products are returned sorted by creation date, with the most recently created products appearing first.
6792
6793| Field | Type | Description
6794|----------|------------|----------
6795| apiKey | credentials| The api key obtained from Stripe.
6796| ids | String | Only return products with the given IDs.
6797| shippable| String | Only return products that can be shipped (i.e., physical, not digital products).
6798| url | String | Only return products with the given url.
6799
6800#### Request example
6801```json
6802{
6803 "apiKey": "...",
6804}
6805```
6806#### Response example
6807```json
6808{
6809 "callback":"success",
6810 "contextWrites":{
6811 "#":{
6812 "to": {
6813 "object": "list",
6814 "url": "/v1/products",
6815 "has_more": false,
6816 "data": [
6817 {
6818 "id": "prod_9I00GcePCVmLik",
6819 "object": "product",
6820 "active": true,
6821 "attributes": [],
6822 "caption": null,
6823 "created": 1475238070,
6824 "deactivate_on": [],
6825 "description": "Test",
6826 "images": [ ],
6827 "livemode": false,
6828 "metadata": {
6829 },
6830 "name": "test",
6831 "package_dimensions": null,
6832 "shippable": true,
6833 "skus": {
6834 "object": "list",
6835 "data": [],
6836 "has_more": false,
6837 "total_count": 0,
6838 "url": "/v1/skus?product=prod_9I00GcePCVmLik\u0026active=true"
6839 },
6840 "updated": 1475238070,
6841 "url": null
6842 },
6843 {...},
6844 {...}
6845 ]
6846 }
6847 }
6848 }
6849}
6850```
6851
6852<a name="deleteProduct"/>
6853## Stripe.deleteProduct
6854Delete a product. Deleting a product is only possible if it has no SKUs associated with it.
6855
6856| Field | Type | Description
6857|----------|------------|----------
6858| apiKey | credentials| The api key obtained from Stripe.
6859| productId| String | The ID of the product to delete.
6860
6861#### Request example
6862```json
6863{
6864 "apiKey": "...",
6865 "productId": "prod_9I00GcePCVmLik"
6866}
6867```
6868#### Response example
6869```json
6870{
6871 "callback":"success",
6872 "contextWrites":{
6873 "#":{
6874 "to":{
6875 "deleted": true,
6876 "id": "pr_18zQ0o2eZvKYlo2CxWcZi2sj"
6877 }
6878 }
6879 }
6880}
6881```
6882
6883<a name="createSKU"/>
6884## Stripe.createSKU
6885Creates a new SKU associated with a product.
6886
6887| Field | Type | Description
6888|------------------|------------|----------
6889| apiKey | credentials| The api key obtained from Stripe.
6890| currency | String | 3-letter ISO code for currency.
6891| inventory | String | Description of the SKU’s inventory.
6892| price | Number | The cost of the item as a nonnegative integer in the smallest currency unit (that is, 100 cents to charge $1.00, or 100 to charge ¥100, Japanese Yen being a 0-decimal currency).
6893| product | String | The ID of the product this SKU is associated with.
6894| active | String | Whether or not the SKU is available for purchase. Default to true.
6895| attributes | JSON | A dictionary of attributes and values for the attributes defined by the product. If, for example, a product’s attributes are ["size", "gender"], a valid SKU has the following dictionary of attributes: {"size": "Medium", "gender": "Unisex"}.
6896| image | String | The URL of an image for this SKU, meant to be displayable to the customer.
6897| metadata | JSON | A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format.
6898| packageDimensions| JSON | The dimensions of this SKU for shipping purposes.
6899
6900#### Request example
6901```json
6902{
6903 "apiKey": "...",
6904 "currency": "usd",
6905 "inventory": {"type": "finite", "quantity": 500},
6906 "price": 1500,
6907 "product": "pr_18zQ0o2eZvKYlo2CxWcZi2sj",
6908 "attributes": {"size": "Medium", "gender": "Unisex"},
6909}
6910```
6911#### Response example
6912```json
6913{
6914 "callback":"success",
6915 "contextWrites":{
6916 "#":{
6917 "to": {
6918 "id": "sku_9BtKAR1ZXD42en",
6919 "object": "sku",
6920 "active": true,
6921 "attributes": {
6922 "color": "Cyan",
6923 "gender": "Unisex",
6924 "size": "Medium"
6925 },
6926 "created": 1473829395,
6927 "currency": "usd",
6928 "image": null,
6929 "inventory": {
6930 "quantity": 500,
6931 "type": "finite",
6932 "value": null
6933 },
6934 "livemode": false,
6935 "metadata": {
6936 },
6937 "package_dimensions": null,
6938 "price": 1500,
6939 "product": "prod_9I00GcePCVmLik",
6940 "updated": 1473829395
6941 }
6942 }
6943 }
6944}
6945```
6946
6947<a name="getSKU"/>
6948## Stripe.getSKU
6949Retrieves the details of an existing SKU. Supply the unique SKU identifier from either a SKU creation request or from the product, and Stripe will return the corresponding SKU information.
6950
6951| Field | Type | Description
6952|-------|------------|----------
6953| apiKey| credentials| The api key obtained from Stripe.
6954| skuId | String | The identifier of the SKU to be retrieved.
6955
6956#### Request example
6957```json
6958{
6959 "apiKey": "...",
6960 "skuId": "sku_9BtKAR1ZXD42en"
6961}
6962```
6963#### Response example
6964```json
6965{
6966 "callback":"success",
6967 "contextWrites":{
6968 "#":{
6969 "to": {
6970 "id": "sku_9BtKAR1ZXD42en",
6971 "object": "sku",
6972 "active": true,
6973 "attributes": {
6974 "color": "Cyan",
6975 "gender": "Unisex",
6976 "size": "Medium"
6977 },
6978 "created": 1473829395,
6979 "currency": "usd",
6980 "image": null,
6981 "inventory": {
6982 "quantity": 500,
6983 "type": "finite",
6984 "value": null
6985 },
6986 "livemode": false,
6987 "metadata": {
6988 },
6989 "package_dimensions": null,
6990 "price": 1500,
6991 "product": "prod_9I00GcePCVmLik",
6992 "updated": 1473829395
6993 }
6994 }
6995 }
6996}
6997```
6998
6999<a name="updateSKU"/>
7000## Stripe.updateSKU
7001Updates the specific SKU by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
7002Note that a SKU's attributes are not editable. Instead, you would need to deactivate the existing SKU and create a new one with the new attribute values.
7003
7004| Field | Type | Description
7005|------------------|------------|----------
7006| apiKey | credentials| The api key obtained from Stripe.
7007| skuId | String | The identifier of the SKU to be updated.
7008| currency | String | 3-letter ISO code for currency.
7009| inventory | String | Description of the SKU’s inventory.
7010| price | String | The cost of the item as a nonnegative integer in the smallest currency unit (that is, 100 cents to charge $1.00, or 100 to charge ¥100, Japanese Yen being a 0-decimal currency).
7011| product | String | The ID of the product this SKU is associated with.
7012| active | String | Whether or not the SKU is available for purchase. Default to true.
7013| attributes | JSON | A dictionary of attributes and values for the attributes defined by the product. If, for example, a product’s attributes are ["size", "gender"], a valid SKU has the following dictionary of attributes: {"size": "Medium", "gender": "Unisex"}.
7014| image | String | The URL of an image for this SKU, meant to be displayable to the customer.
7015| metadata | JSON | A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format.
7016| packageDimensions| JSON | The dimensions of this SKU for shipping purposes.
7017
7018#### Request example
7019```json
7020{
7021 "apiKey": "...",
7022 "skuId": "sk_18tVYF2eZvKYlo2CbiWi3yjT",
7023}
7024```
7025#### Response example
7026```json
7027{
7028 "callback":"success",
7029 "contextWrites":{
7030 "#":{
7031 "to":{
7032 "id": "sku_9BtKAR1ZXD42en",
7033 "object": "sku",
7034 "active": true,
7035 "attributes": {
7036 "color": "Cyan",
7037 "gender": "Unisex",
7038 "size": "Medium"
7039 },
7040 "created": 1473829395,
7041 "currency": "usd",
7042 "image": null,
7043 "inventory": {
7044 "quantity": 500,
7045 "type": "finite",
7046 "value": null
7047 },
7048 "livemode": false,
7049 "metadata": {
7050 "order_id": "6735"
7051 },
7052 "package_dimensions": null,
7053 "price": 1500,
7054 "product": "prod_9I00GcePCVmLik",
7055 "updated": 1473829395
7056 }
7057 }
7058 }
7059}
7060```
7061
7062<a name="getSKUList"/>
7063## Stripe.getSKUList
7064Returns a list of your SKUs. The SKUs are returned sorted by creation date, with the most recently created SKUs appearing first.
7065
7066| Field | Type | Description
7067|-----------|------------|----------
7068| apiKey | credentials| The api key obtained from Stripe.
7069| attributes| String |
7070| ids | String | Only return SKUs with the given IDs.
7071| productId | String | The ID of the product whose SKUs will be retrieved.
7072
7073#### Request example
7074```json
7075{
7076 "apiKey": "...",
7077}
7078```
7079#### Response example
7080```json
7081{
7082 "callback":"success",
7083 "contextWrites":{
7084 "#":{
7085 "to":{
7086 "object": "list",
7087 "url": "/v1/skus",
7088 "has_more": false,
7089 "data": [
7090 {
7091 "id": "sk_18tVYF2eZvKYlo2CbiWi3yjT",
7092 "object": "sku",
7093 "active": true,
7094 "attributes": {
7095 "color": "Cyan",
7096 "gender": "Unisex",
7097 "size": "Medium"
7098 },
7099 "created": 1473829395,
7100 "currency": "usd",
7101 "image": null,
7102 "inventory": {
7103 "quantity": 500,
7104 "type": "finite",
7105 "value": null
7106 },
7107 "livemode": false,
7108 "metadata": {
7109 },
7110 "package_dimensions": null,
7111 "price": 1500,
7112 "product": "prod_9I00GcePCVmLik",
7113 "updated": 1473829395
7114 },
7115 {...},
7116 {...}
7117 ]
7118 }
7119 }
7120 }
7121}
7122```
7123
7124<a name="deleteSKU"/>
7125## Stripe.deleteSKU
7126Delete a SKU. Deleting a SKU is only possible until it has been used in an order.
7127
7128| Field | Type | Description
7129|-------|------------|----------
7130| apiKey| credentials| The api key obtained from Stripe.
7131| skuId | String | The identifier of the SKU to be deleted.
7132
7133#### Request example
7134```json
7135{
7136 "apiKey": "...",
7137 "skuId": "sku_9BtKAR1ZXD42en"
7138}
7139```
7140#### Response example
7141```json
7142{
7143 "callback":"success",
7144 "contextWrites":{
7145 "#":{
7146 "to":{
7147 "deleted": true,
7148 "id": "sku_9BtKAR1ZXD42en"
7149 }
7150 }
7151 }
7152}
7153```
7154
7155<a name="createCoupon"/>
7156## Stripe.createCoupon
7157You 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.
7158A 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.
7159
7160| Field | Type | Description
7161|-----------------|------------|----------
7162| apiKey | credentials| The api key obtained from Stripe.
7163| couponId | String | Unique string of your choice that will be used to identify this coupon when applying it to a customer. This is often a specific code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you can leave the ID blank and we’ll generate a random code for you.
7164| duration | String | Specifies how long the discount will be in effect. Can be `forever`, `once`, or `repeating`.
7165| amountOff | String | A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed)
7166| currency | String | Currency of the amount_off parameter (required if amount_off is passed)
7167| durationInMonths| String | Required only if duration is repeating, in which case it must be a positive integer that specifies the number of months the discount will be in effect.
7168| maxRedemptions | String | 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.
7169| metadata | JSON | 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 null and then saving.
7170| percentOff | String | A positive integer between 1 and 100 that represents the discount the coupon will apply (required if amount_off is not passed)
7171| redeemBy | String | Unix timestamp specifying the last time at which the coupon can be redeemed. After the redeem_by date, the coupon can no longer be applied to new customers.
7172
7173#### Request example
7174```json
7175{
7176 "apiKey": "...",
7177 "couponId": "plana-5000-yearly-30-off",
7178 "duration": "repeating",
7179 "currency": "usd",
7180 "durationInMonths": "3",
7181 "percentOff": "20",
7182}
7183```
7184#### Response example
7185```json
7186{
7187 "callback":"success",
7188 "contextWrites":{
7189 "#":{
7190 "to": {
7191 "id": "plana-5000-yearly-30-off",
7192 "object": "coupon",
7193 "amount_off": 1572,
7194 "created": 1475026549,
7195 "currency": "usd",
7196 "duration": "forever",
7197 "duration_in_months": null,
7198 "livemode": false,
7199 "max_redemptions": null,
7200 "metadata": {
7201 },
7202 "percent_off": null,
7203 "redeem_by": null,
7204 "times_redeemed": 0,
7205 "valid": true
7206 }
7207 }
7208 }
7209}
7210```
7211
7212<a name="getCoupon"/>
7213## Stripe.getCoupon
7214Retrieves the coupon with the given ID.
7215
7216| Field | Type | Description
7217|---------|------------|----------
7218| apiKey | credentials| The api key obtained from Stripe.
7219| couponId| String | Unique string of your choice that will be used to identify this coupon when applying it to a customer. This is often a specific code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you can leave the ID blank and we’ll generate a random code for you.
7220
7221#### Request example
7222```json
7223{
7224 "apiKey": "...",
7225 "couponId": "plana-5000-yearly-30-off"
7226}
7227```
7228#### Response example
7229```json
7230{
7231 "callback":"success",
7232 "contextWrites":{
7233 "#":{
7234 "to": {
7235 "id": "plana-5000-yearly-30-off",
7236 "object": "coupon",
7237 "amount_off": 1572,
7238 "created": 1475026549,
7239 "currency": "usd",
7240 "duration": "forever",
7241 "duration_in_months": null,
7242 "livemode": false,
7243 "max_redemptions": null,
7244 "metadata": {
7245 },
7246 "percent_off": null,
7247 "redeem_by": null,
7248 "times_redeemed": 0,
7249 "valid": true
7250 }
7251 }
7252 }
7253}
7254```
7255
7256<a name="updateCoupon"/>
7257## Stripe.updateCoupon
7258Updates the metadata of a coupon. Other coupon details (currency, duration, amount_off) are, by design, not editable.
7259
7260| Field | Type | Description
7261|---------|------------|----------
7262| apiKey | credentials| The api key obtained from Stripe.
7263| couponId| String | Unique string of your choice that will be used to identify this coupon when applying it to a customer. This is often a specific code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you can leave the ID blank and we’ll generate a random code for you.
7264| metadata| JSON | 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 null and then saving.
7265
7266#### Request example
7267```json
7268{
7269 "apiKey": "...",
7270 "couponId": "plana-5000-yearly-30-off",
7271 "metadata": "..."
7272}
7273```
7274#### Response example
7275```json
7276{
7277 "callback":"success",
7278 "contextWrites":{
7279 "#":{
7280 "to": {
7281 "id": "plana-5000-yearly-30-off",
7282 "object": "coupon",
7283 "amount_off": 1572,
7284 "created": 1475026549,
7285 "currency": "usd",
7286 "duration": "forever",
7287 "duration_in_months": null,
7288 "livemode": false,
7289 "max_redemptions": null,
7290 "metadata": {
7291 "order_id": "6735"
7292 },
7293 "percent_off": null,
7294 "redeem_by": null,
7295 "times_redeemed": 0,
7296 "valid": true
7297 }
7298 }
7299 }
7300}
7301```
7302
7303<a name="deleteCoupon"/>
7304## Stripe.deleteCoupon
7305You 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.
7306
7307
7308| Field | Type | Description
7309|---------|------------|----------
7310| apiKey | credentials| The api key obtained from Stripe.
7311| couponId| String | Unique string of your choice that will be used to identify this coupon when applying it to a customer. This is often a specific code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you can leave the ID blank and we’ll generate a random code for you.
7312
7313#### Request example
7314```json
7315{
7316 "apiKey": "...",
7317 "couponId": "plana-5000-yearly-30-off"
7318}
7319```
7320#### Response example
7321```json
7322{
7323 "callback":"success",
7324 "contextWrites":{
7325 "#":{
7326 "to": {
7327 "deleted": true,
7328 "id": "plana-5000-yearly-30-off"
7329 }
7330 }
7331 }
7332}
7333```
7334
7335<a name="getCouponList"/>
7336## Stripe.getCouponList
7337Returns a list of your coupons.
7338
7339| Field | Type | Description
7340|-------|------------|----------
7341| apiKey| credentials| The api key obtained from Stripe.
7342
7343#### Request example
7344```json
7345{
7346 "apiKey": "..."
7347}
7348```
7349#### Response example
7350```json
7351{
7352 "callback":"success",
7353 "contextWrites":{
7354 "#":{
7355 "to": {
7356 "object": "list",
7357 "url": "/v1/coupons",
7358 "has_more": false,
7359 "data": [
7360 {
7361 "id": "plana-5000-yearly-30-off",
7362 "object": "coupon",
7363 "amount_off": 1572,
7364 "created": 1475026549,
7365 "currency": "usd",
7366 "duration": "forever",
7367 "duration_in_months": null,
7368 "livemode": false,
7369 "max_redemptions": null,
7370 "metadata": {
7371 },
7372 "percent_off": null,
7373 "redeem_by": null,
7374 "times_redeemed": 0,
7375 "valid": true
7376 },
7377 {...},
7378 {...}
7379 ]
7380 }
7381 }
7382 }
7383}
7384```
7385
7386<a name="deleteCustomerDiscount"/>
7387## Stripe.deleteCustomerDiscount
7388Removes the currently applied discount on a customer.
7389
7390| Field | Type | Description
7391|-----------|------------|----------
7392| apiKey | credentials| The api key obtained from Stripe.
7393| customerId| String | Id of customer to delete.
7394
7395#### Request example
7396```json
7397{
7398 "apiKey": "...",
7399 "customerId": "cus_9I1yraWQEUlyFj"
7400}
7401```
7402#### Response example
7403```json
7404{
7405 "callback":"success",
7406 "contextWrites":{
7407 "#":{
7408 "to": {
7409 "deleted": true,
7410 "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
7411 }
7412 }
7413 }
7414}
7415```
7416
7417<a name="deleteSubscriptionDiscount"/>
7418## Stripe.deleteSubscriptionDiscount
7419Removes the currently applied discount on a subscription.
7420
7421| Field | Type | Description
7422|---------------|------------|----------
7423| apiKey | credentials| The api key obtained from Stripe.
7424| subscriptionId| String | Id of subscribtion to delete.
7425
7426#### Request example
7427```json
7428{
7429 "apiKey": "...",
7430 "subscriptionId": "sub_9I1lOo21wR8yCe"
7431}
7432```
7433#### Response example
7434```json
7435{
7436 "callback":"success",
7437 "contextWrites":{
7438 "#":{
7439 "to": {
7440 "deleted": true,
7441 "id": "di_14Rjd02eZvKYlo2Cl8SvGHtJ"
7442 }
7443 }
7444 }
7445}
7446```
7447
7448<a name="createInvoice"/>
7449## Stripe.createInvoice
7450If 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.
7451Once you create the invoice, it’ll be picked up and paid automatically, though you can choose to pay it right away.
7452
7453| Field | Type | Description
7454|--------------------|------------|----------
7455| apiKey | credentials| The api key obtained from Stripe.
7456| customer | String | Customer Id
7457| applicationFee | String | A fee in cents that will be applied to the invoice and transferred to the application owner’s Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee.
7458| description | String | 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.
7459| metadata | JSON | 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 null and then saving.
7460| statementDescriptor| String | Extra information about a charge for the customer’s credit card statement.
7461| subscription | String | The ID of the subscription to invoice. If not set, the created invoice will include all pending invoice items for the customer. If set, the created invoice will exclude pending invoice items that pertain to other subscriptions.
7462| taxPercent | String | The percent tax rate applied to the invoice, represented as a decimal number.
7463
7464#### Request example
7465```json
7466{
7467 "apiKey": "...",
7468 "customer": "cus_9I1yraWQEUlyFj",
7469}
7470```
7471#### Response example
7472```json
7473{
7474 "callback":"success",
7475 "contextWrites":{
7476 "#":{
7477 "to": {
7478 "id": "in_18zRtZ2eZvKYlo2Cj0FPqd80",
7479 "object": "invoice",
7480 "amount_due": 999,
7481 "application_fee": null,
7482 "attempt_count": 0,
7483 "attempted": false,
7484 "charge": null,
7485 "closed": false,
7486 "currency": "usd",
7487 "customer": "cus_9I1yraWQEUlyFj",
7488 "date": 1475245309,
7489 "description": null,
7490 "discount": null,
7491 "ending_balance": null,
7492 "forgiven": false,
7493 "lines": {
7494 "data": [
7495 {
7496 "id": "ii_18yKaN2eZvKYlo2Co22dhawI",
7497 "object": "line_item",
7498 "amount": 999,
7499 "currency": "usd",
7500 "description": "Unused time on Foo after 27 Sep 2016",
7501 "discountable": false,
7502 "livemode": false,
7503 "metadata": {
7504 },
7505 "period": {
7506 "start": 1474978883,
7507 "end": 1474978883
7508 },
7509 "plan": {
7510 "id": "16598foo1474978869",
7511 "object": "plan",
7512 "amount": 100,
7513 "created": 1474978873,
7514 "currency": "usd",
7515 "interval": "week",
7516 "interval_count": 1,
7517 "livemode": false,
7518 "metadata": {
7519 },
7520 "name": "Foo",
7521 "statement_descriptor": null,
7522 "trial_period_days": null
7523 },
7524 "proration": true,
7525 "quantity": 1,
7526 "subscription": "sub_9GsKNJuNtntFFH",
7527 "type": "invoiceitem"
7528 }
7529 ],
7530 "total_count": 1,
7531 "object": "list",
7532 "url": "/v1/invoices/in_18zRtZ2eZvKYlo2Cj0FPqd80/lines"
7533 },
7534 "livemode": false,
7535 "metadata": {
7536 },
7537 "next_payment_attempt": 1475248909,
7538 "paid": false,
7539 "period_end": 1475245268,
7540 "period_start": 1472653268,
7541 "receipt_number": null,
7542 "starting_balance": 0,
7543 "statement_descriptor": null,
7544 "subscription": "sub_8vBAxymotaxUiw",
7545 "subtotal": 999,
7546 "tax": null,
7547 "tax_percent": null,
7548 "total": 999,
7549 "webhooks_delivered_at": 1475245329
7550 }
7551 }
7552 }
7553}
7554```
7555
7556<a name="getInvoice"/>
7557## Stripe.getInvoice
7558Retrieves the invoice with the given ID.
7559
7560| Field | Type | Description
7561|----------|------------|----------
7562| apiKey | credentials| The api key obtained from Stripe.
7563| invoiceId| String | Invoice id.
7564
7565#### Request example
7566```json
7567{
7568 "apiKey": "...",
7569 "invoiceId": "in_18zRtZ2eZvKYlo2Cj0FPqd80"
7570}
7571```
7572#### Response example
7573```json
7574{
7575 "callback":"success",
7576 "contextWrites":{
7577 "#":{
7578 "to": {
7579 "id": "in_18zRtZ2eZvKYlo2Cj0FPqd80",
7580 "object": "invoice",
7581 "amount_due": 999,
7582 "application_fee": null,
7583 "attempt_count": 0,
7584 "attempted": false,
7585 "charge": null,
7586 "closed": false,
7587 "currency": "usd",
7588 "customer": "cus_9I1yraWQEUlyFj",
7589 "date": 1475245309,
7590 "description": null,
7591 "discount": null,
7592 "ending_balance": null,
7593 "forgiven": false,
7594 "lines": {
7595 "data": [
7596 {
7597 "id": "sub_9I1lOo21wR8yCe",
7598 "object": "line_item",
7599 "amount": 999,
7600 "currency": "usd",
7601 "description": null,
7602 "discountable": true,
7603 "livemode": true,
7604 "metadata": {
7605 },
7606 "period": {
7607 "start": 1477836560,
7608 "end": 1480514960
7609 },
7610 "plan": {
7611 "id": "diamond-beginner-305",
7612 "object": "plan",
7613 "amount": 999,
7614 "created": 1475244516,
7615 "currency": "usd",
7616 "interval": "month",
7617 "interval_count": 1,
7618 "livemode": false,
7619 "metadata": {
7620 },
7621 "name": "Diamond Beginner",
7622 "statement_descriptor": null,
7623 "trial_period_days": null
7624 },
7625 "proration": false,
7626 "quantity": 1,
7627 "subscription": null,
7628 "type": "subscription"
7629 }
7630 ],
7631 "total_count": 1,
7632 "object": "list",
7633 "url": "/v1/invoices/in_18zRtZ2eZvKYlo2Cj0FPqd80/lines"
7634 },
7635 "livemode": false,
7636 "metadata": {
7637 },
7638 "next_payment_attempt": 1475248909,
7639 "paid": false,
7640 "period_end": 1475245268,
7641 "period_start": 1472653268,
7642 "receipt_number": null,
7643 "starting_balance": 0,
7644 "statement_descriptor": null,
7645 "subscription": "sub_8vBAxymotaxUiw",
7646 "subtotal": 999,
7647 "tax": null,
7648 "tax_percent": null,
7649 "total": 999,
7650 "webhooks_delivered_at": 1475245329
7651 }
7652 }
7653 }
7654}
7655```
7656
7657<a name="getInvoiceLineItems"/>
7658## Stripe.getInvoiceLineItems
7659When 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.
7660
7661| Field | Type | Description
7662|--------------------------|------------|----------
7663| apiKey | credentials| The api key obtained from Stripe.
7664| invoice | String | Invoice id.
7665| coupon | String | Counpon id.
7666| customer | String | In the case of upcoming invoices, the customer of the upcoming invoice is required. In other cases it is ignored.
7667| subscription | String | In the case of upcoming invoices, the subscription of the upcoming invoice is optional. In other cases it is ignored.
7668| subscriptionPlan | String | Subscription Plan
7669| subscriptionProrate | String | Subscription Prorate
7670| subscriptionProrationDate| String | Subscription Proration Date
7671| subscriptionQuantity | String | Subscription Quantity
7672| subscriptionTrialEnd | String | Subscription Trial End
7673
7674#### Request example
7675```json
7676{
7677 "apiKey": "...",
7678 "invoice": "in_18zRtZ2eZvKYlo2Cj0FPqd80",
7679}
7680```
7681#### Response example
7682```json
7683{
7684 "callback":"success",
7685 "contextWrites":{
7686 "#":{
7687 "to": {
7688 "object": "list",
7689 "url": "/v1/invoices/in_18zRtZ2eZvKYlo2Cj0FPqd80/lines",
7690 "has_more": false,
7691 "data": [
7692 {
7693 "id": "ii_18yKaN2eZvKYlo2Co22dhawI",
7694 "object": "line_item",
7695 "amount": -100,
7696 "currency": "usd",
7697 "description": "Unused time on Foo after 27 Sep 2016",
7698 "discountable": false,
7699 "livemode": false,
7700 "metadata": {
7701 },
7702 "period": {
7703 "start": 1474978883,
7704 "end": 1474978883
7705 },
7706 "plan": {
7707 "id": "16598foo1474978869",
7708 "object": "plan",
7709 "amount": 100,
7710 "created": 1474978873,
7711 "currency": "usd",
7712 "interval": "week",
7713 "interval_count": 1,
7714 "livemode": false,
7715 "metadata": {
7716 },
7717 "name": "Foo",
7718 "statement_descriptor": null,
7719 "trial_period_days": null
7720 },
7721 "proration": true,
7722 "quantity": 1,
7723 "subscription": "sub_9GsKNJuNtntFFH",
7724 "type": "invoiceitem"
7725 },
7726 {...},
7727 {...}
7728 ]
7729 }
7730 }
7731 }
7732}
7733```
7734
7735<a name="updateInvoice"/>
7736## Stripe.updateInvoice
7737Until 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.
7738
7739| Field | Type | Description
7740|--------------------|------------|----------
7741| apiKey | credentials| The api key obtained from Stripe.
7742| invoiceId | String | Invoice id.
7743| applicationFee | String | A fee in cents that will be applied to the invoice and transferred to the application owner’s Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee.
7744| description | String | 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.
7745| metadata | String | 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 null and then saving.
7746| statementDescriptor| String | Extra information about a charge for the customer’s credit card statement.
7747| subscription | String | The ID of the subscription to invoice. If not set, the created invoice will include all pending invoice items for the customer. If set, the created invoice will exclude pending invoice items that pertain to other subscriptions.
7748| forgiven | String | Boolean representing whether an invoice is forgiven or not. To forgive an invoice, pass true. Forgiving an invoice instructs us to update the subscription status as if the invoice were successfully paid. Once an invoice has been forgiven, it cannot be unforgiven or reopened.
7749| closed | String | Boolean representing whether an invoice is closed or not. To close an invoice, pass true.
7750| taxPercent | String | The percent tax rate applied to the invoice, represented as a decimal number.
7751
7752#### Request example
7753```json
7754{
7755 "apiKey": "...",
7756 "invoiceId": "in_18zRtZ2eZvKYlo2Cj0FPqd80",
7757 "closed": "true",
7758}
7759```
7760#### Response example
7761```json
7762{
7763 "callback":"success",
7764 "contextWrites":{
7765 "#":{
7766 "to": {
7767 "id": "in_18zRtZ2eZvKYlo2Cj0FPqd80",
7768 "object": "invoice",
7769 "amount_due": 999,
7770 "application_fee": null,
7771 "attempt_count": 0,
7772 "attempted": false,
7773 "charge": null,
7774 "closed": true,
7775 "currency": "usd",
7776 "customer": "cus_9I1yraWQEUlyFj",
7777 "date": 1475245309,
7778 "description": null,
7779 "discount": null,
7780 "ending_balance": null,
7781 "forgiven": false,
7782 "lines": {
7783 "data": [
7784 {
7785 "id": "sub_9I1lOo21wR8yCe",
7786 "object": "line_item",
7787 "amount": 999,
7788 "currency": "usd",
7789 "description": null,
7790 "discountable": true,
7791 "livemode": true,
7792 "metadata": {
7793 },
7794 "period": {
7795 "start": 1477836560,
7796 "end": 1480514960
7797 },
7798 "plan": {
7799 "id": "diamond-beginner-305",
7800 "object": "plan",
7801 "amount": 999,
7802 "created": 1475244516,
7803 "currency": "usd",
7804 "interval": "month",
7805 "interval_count": 1,
7806 "livemode": false,
7807 "metadata": {
7808 },
7809 "name": "Diamond Beginner",
7810 "statement_descriptor": null,
7811 "trial_period_days": null
7812 },
7813 "proration": false,
7814 "quantity": 1,
7815 "subscription": null,
7816 "type": "subscription"
7817 }
7818 ],
7819 "total_count": 1,
7820 "object": "list",
7821 "url": "/v1/invoices/in_18zRtZ2eZvKYlo2Cj0FPqd80/lines"
7822 },
7823 "livemode": false,
7824 "metadata": {
7825 },
7826 "next_payment_attempt": 1475248909,
7827 "paid": false,
7828 "period_end": 1475245268,
7829 "period_start": 1472653268,
7830 "receipt_number": null,
7831 "starting_balance": 0,
7832 "statement_descriptor": null,
7833 "subscription": "sub_8vBAxymotaxUiw",
7834 "subtotal": 999,
7835 "tax": null,
7836 "tax_percent": null,
7837 "total": 999,
7838 "webhooks_delivered_at": 1475245329
7839 }
7840 }
7841 }
7842}
7843```
7844
7845<a name="payInvoice"/>
7846## Stripe.payInvoice
7847Stripe 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.
7848
7849| Field | Type | Description
7850|----------|------------|----------
7851| apiKey | credentials| The api key obtained from Stripe.
7852| invoiceId| String | Invoice id.
7853
7854#### Request example
7855```json
7856{
7857 "apiKey": "...",
7858 "invoiceId": "in_18zRtZ2eZvKYlo2Cj0FPqd80"
7859}
7860```
7861#### Response example
7862```json
7863{
7864 "callback":"success",
7865 "contextWrites":{
7866 "#":{
7867 "to": {
7868 "id": "in_18zRtZ2eZvKYlo2Cj0FPqd80",
7869 "object": "invoice",
7870 "amount_due": 999,
7871 "application_fee": null,
7872 "attempt_count": 0,
7873 "attempted": true,
7874 "charge": "ch_18zRvN2eZvKYlo2CT5LTwgEC",
7875 "closed": false,
7876 "currency": "usd",
7877 "customer": "cus_9I1yraWQEUlyFj",
7878 "date": 1475245309,
7879 "description": null,
7880 "discount": null,
7881 "ending_balance": null,
7882 "forgiven": false,
7883 "lines": {
7884 "data": [
7885 {
7886 "id": "ii_18yKaN2eZvKYlo2Co22dhawI",
7887 "object": "line_item",
7888 "amount": 999,
7889 "currency": "usd",
7890 "description": "Unused time on Foo after 27 Sep 2016",
7891 "discountable": false,
7892 "livemode": false,
7893 "metadata": {
7894 },
7895 "period": {
7896 "start": 1474978883,
7897 "end": 1474978883
7898 },
7899 "plan": {
7900 "id": "16598foo1474978869",
7901 "object": "plan",
7902 "amount": 100,
7903 "created": 1474978873,
7904 "currency": "usd",
7905 "interval": "week",
7906 "interval_count": 1,
7907 "livemode": false,
7908 "metadata": {
7909 },
7910 "name": "Foo",
7911 "statement_descriptor": null,
7912 "trial_period_days": null
7913 },
7914 "proration": true,
7915 "quantity": 1,
7916 "subscription": "sub_9GsKNJuNtntFFH",
7917 "type": "invoiceitem"
7918 }
7919 ],
7920 "total_count": 1,
7921 "object": "list",
7922 "url": "/v1/invoices/in_18zRtZ2eZvKYlo2Cj0FPqd80/lines"
7923 },
7924 "livemode": false,
7925 "metadata": {
7926 },
7927 "next_payment_attempt": 1475248909,
7928 "paid": true,
7929 "period_end": 1475245268,
7930 "period_start": 1472653268,
7931 "receipt_number": null,
7932 "starting_balance": 0,
7933 "statement_descriptor": null,
7934 "subscription": "sub_8vBAxymotaxUiw",
7935 "subtotal": 999,
7936 "tax": null,
7937 "tax_percent": null,
7938 "total": 999,
7939 "webhooks_delivered_at": 1475245329,
7940 "last_payment_attempt": null
7941 }
7942 }
7943 }
7944}
7945```
7946
7947<a name="getInvoiceList"/>
7948## Stripe.getInvoiceList
7949You 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.
7950
7951| Field | Type | Description
7952|---------|------------|----------
7953| apiKey | credentials| The api key obtained from Stripe.
7954| customer| String | The identifier of the customer whose invoices to return. If none is provided, all invoices will be returned.
7955
7956#### Request example
7957```json
7958{
7959 "apiKey": "...",
7960}
7961```
7962#### Response example
7963```json
7964{
7965 "callback":"success",
7966 "contextWrites":{
7967 "#":{
7968 "to": {
7969 "object": "list",
7970 "url": "/v1/invoices",
7971 "has_more": false,
7972 "data": [
7973 {
7974 "id": "in_18zRtZ2eZvKYlo2Cj0FPqd80",
7975 "object": "invoice",
7976 "amount_due": 999,
7977 "application_fee": null,
7978 "attempt_count": 0,
7979 "attempted": false,
7980 "charge": null,
7981 "closed": false,
7982 "currency": "usd",
7983 "customer": "cus_9I1yraWQEUlyFj",
7984 "date": 1475245309,
7985 "description": null,
7986 "discount": null,
7987 "ending_balance": null,
7988 "forgiven": false,
7989 "lines": {
7990 "data": [
7991 {
7992 "id": "sub_9I1lOo21wR8yCe",
7993 "object": "line_item",
7994 "amount": 999,
7995 "currency": "usd",
7996 "description": null,
7997 "discountable": true,
7998 "livemode": true,
7999 "metadata": {
8000 },
8001 "period": {
8002 "start": 1477836560,
8003 "end": 1480514960
8004 },
8005 "plan": {
8006 "id": "diamond-beginner-305",
8007 "object": "plan",
8008 "amount": 999,
8009 "created": 1475244516,
8010 "currency": "usd",
8011 "interval": "month",
8012 "interval_count": 1,
8013 "livemode": false,
8014 "metadata": {
8015 },
8016 "name": "Diamond Beginner",
8017 "statement_descriptor": null,
8018 "trial_period_days": null
8019 },
8020 "proration": false,
8021 "quantity": 1,
8022 "subscription": null,
8023 "type": "subscription"
8024 }
8025 ],
8026 "total_count": 1,
8027 "object": "list",
8028 "url": "/v1/invoices/in_18zRtZ2eZvKYlo2Cj0FPqd80/lines"
8029 },
8030 "livemode": false,
8031 "metadata": {
8032 },
8033 "next_payment_attempt": 1475248909,
8034 "paid": false,
8035 "period_end": 1475245268,
8036 "period_start": 1472653268,
8037 "receipt_number": null,
8038 "starting_balance": 0,
8039 "statement_descriptor": null,
8040 "subscription": "sub_8vBAxymotaxUiw",
8041 "subtotal": 999,
8042 "tax": null,
8043 "tax_percent": null,
8044 "total": 999,
8045 "webhooks_delivered_at": 1475245329
8046 },
8047 {...},
8048 {...}
8049 ]
8050 }
8051 }
8052 }
8053}
8054```
8055
8056<a name="createInvoiceItem"/>
8057## Stripe.createInvoiceItem
8058Adds an arbitrary charge or credit to the customer’s upcoming invoice.
8059
8060| Field | Type | Description
8061|-------------|------------|----------
8062| apiKey | credentials| The api key obtained from Stripe.
8063| amount | Number | 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.
8064| currency | String | 3-letter ISO code for currency.
8065| customer | String | The ID of the customer who will be billed when this invoice item is billed.
8066| description | String | 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 null and then saving.
8067| discountable| String | Controls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items.
8068| invoice | String | The ID of an existing invoice to add this invoice item to. When left blank, the invoice item will be added to the next upcoming scheduled invoice. Use this when adding invoice items in response to an invoice.created webhook. You cannot add an invoice item to an invoice that has already been paid, attempted or closed.
8069| metadata | JSON | A set of key/value pairs that you can attach to an invoice item object. It can be useful for storing additional information about the invoice item in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
8070| subscription| String | 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.
8071
8072#### Request example
8073```json
8074{
8075 "apiKey": "...",
8076 "amount": 2500,
8077 "currency": "usd",
8078 "customer": "cus_9I1yraWQEUlyFj",
8079 "description": "One-time setup fee",
8080}
8081```
8082#### Response example
8083```json
8084{
8085 "callback":"success",
8086 "contextWrites":{
8087 "#":{
8088 "to": {
8089 "id": "ii_18yKaN2eZvKYlo2Co22dhawI",
8090 "object": "invoiceitem",
8091 "amount": 999,
8092 "currency": "usd",
8093 "customer": "cus_9I1yraWQEUlyFj",
8094 "date": 1474978883,
8095 "description": "Unused time on Foo after 27 Sep 2016",
8096 "discountable": false,
8097 "invoice": "in_18yKaO2eZvKYlo2CXEisc1Ih",
8098 "livemode": false,
8099 "metadata": {
8100 },
8101 "period": {
8102 "start": 1474978883,
8103 "end": 1475583679
8104 },
8105 "plan": {
8106 "id": "16598foo1474978869",
8107 "object": "plan",
8108 "amount": 100,
8109 "created": 1474978873,
8110 "currency": "usd",
8111 "interval": "week",
8112 "interval_count": 1,
8113 "livemode": false,
8114 "metadata": {
8115 },
8116 "name": "Foo",
8117 "statement_descriptor": null,
8118 "trial_period_days": null
8119 },
8120 "proration": true,
8121 "quantity": 1,
8122 "subscription": "sub_9GsKNJuNtntFFH"
8123 }
8124 }
8125 }
8126}
8127```
8128
8129<a name="getInvoiceItem"/>
8130## Stripe.getInvoiceItem
8131Retrieves the invoice item with the given ID.
8132
8133| Field | Type | Description
8134|------------|------------|----------
8135| apiKey | credentials| The api key obtained from Stripe.
8136| invoiceitem| String | The ID of the desired invoice item.
8137
8138#### Request example
8139```json
8140{
8141 "apiKey": "...",
8142 "invoiceitem": "ii_18yKaN2eZvKYlo2Co22dhawI"
8143}
8144```
8145#### Response example
8146```json
8147{
8148 "callback":"success",
8149 "contextWrites":{
8150 "#":{
8151 "to": {
8152 "id": "ii_18yKaN2eZvKYlo2Co22dhawI",
8153 "object": "invoiceitem",
8154 "amount": 999,
8155 "currency": "usd",
8156 "customer": "cus_9I1yraWQEUlyFj",
8157 "date": 1474978883,
8158 "description": "Unused time on Foo after 27 Sep 2016",
8159 "discountable": false,
8160 "invoice": "in_18yKaO2eZvKYlo2CXEisc1Ih",
8161 "livemode": false,
8162 "metadata": {
8163 },
8164 "period": {
8165 "start": 1474978883,
8166 "end": 1475583679
8167 },
8168 "plan": {
8169 "id": "16598foo1474978869",
8170 "object": "plan",
8171 "amount": 100,
8172 "created": 1474978873,
8173 "currency": "usd",
8174 "interval": "week",
8175 "interval_count": 1,
8176 "livemode": false,
8177 "metadata": {
8178 },
8179 "name": "Foo",
8180 "statement_descriptor": null,
8181 "trial_period_days": null
8182 },
8183 "proration": true,
8184 "quantity": 1,
8185 "subscription": "sub_9GsKNJuNtntFFH"
8186 }
8187 }
8188 }
8189}
8190```
8191
8192<a name="updateInvoiceItem"/>
8193## Stripe.updateInvoiceItem
8194Updates 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.
8195
8196| Field | Type | Description
8197|-------------|------------|----------
8198| apiKey | credentials| The api key obtained from Stripe.
8199| itemId | String | Item id.
8200| amount | Number | 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.
8201| description | String | 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 null and then saving.
8202| discountable| String | Controls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items. Cannot be set to true for prorations.
8203| metadata | JSON | 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 null and then saving. To clear all keys, set metadata to null, then save.
8204
8205#### Request example
8206```json
8207{
8208 "apiKey": "...",
8209 "itemId": "ii_18yKaN2eZvKYlo2Co22dhawI",
8210 "amount": 2500,
8211 "description": "One-time setup fee",
8212}
8213```
8214#### Response example
8215```json
8216{
8217 "callback":"success",
8218 "contextWrites":{
8219 "#":{
8220 "to": {
8221 "id": "ii_18yKaN2eZvKYlo2Co22dhawI",
8222 "object": "invoiceitem",
8223 "amount": 2500,
8224 "currency": "usd",
8225 "customer": "cus_9I1yraWQEUlyFj",
8226 "date": 1474978883,
8227 "description": "One-time setup fee",
8228 "discountable": false,
8229 "invoice": "in_18yKaO2eZvKYlo2CXEisc1Ih",
8230 "livemode": false,
8231 "metadata": {
8232 },
8233 "period": {
8234 "start": 1474978883,
8235 "end": 1475583679
8236 },
8237 "plan": {
8238 "id": "16598foo1474978869",
8239 "object": "plan",
8240 "amount": 100,
8241 "created": 1474978873,
8242 "currency": "usd",
8243 "interval": "week",
8244 "interval_count": 1,
8245 "livemode": false,
8246 "metadata": {
8247 },
8248 "name": "Foo",
8249 "statement_descriptor": null,
8250 "trial_period_days": null
8251 },
8252 "proration": true,
8253 "quantity": 1,
8254 "subscription": "sub_9GsKNJuNtntFFH"
8255 }
8256 }
8257 }
8258}
8259```
8260
8261<a name="deleteInvoiceItem"/>
8262## Stripe.deleteInvoiceItem
8263Removes an invoice item from the upcoming invoice. Removing an invoice item is only possible before the invoice it’s attached to is closed.
8264
8265| Field | Type | Description
8266|------------|------------|----------
8267| apiKey | credentials| The api key obtained from Stripe.
8268| invoiceitem| String | The ID of the desired invoice item.
8269
8270#### Request example
8271```json
8272{
8273 "apiKey": "...",
8274 "invoiceitem": "ii_18yKaN2eZvKYlo2Co22dhawI"
8275}
8276```
8277#### Response example
8278```json
8279{
8280 "callback":"success",
8281 "contextWrites":{
8282 "#":{
8283 "to": {
8284 "deleted": true,
8285 "id": "ii_18yKaN2eZvKYlo2Co22dhawI"
8286 }
8287 }
8288 }
8289}
8290```
8291
8292<a name="getInvoiceItemsList"/>
8293## Stripe.getInvoiceItemsList
8294Returns a list of your invoice items. Invoice items are returned sorted by creation date, with the most recently created invoice items appearing first.
8295
8296| Field | Type | Description
8297|---------|------------|----------
8298| apiKey | credentials| The api key obtained from Stripe.
8299| customer| String | The identifier of the customer whose invoice items to return. If none is provided, all invoice items will be returned.
8300
8301#### Request example
8302```json
8303{
8304 "apiKey": "...",
8305}
8306```
8307#### Response example
8308```json
8309{
8310 "callback":"success",
8311 "contextWrites":{
8312 "#":{
8313 "to": {
8314 "object": "list",
8315 "url": "/v1/invoiceitems",
8316 "has_more": false,
8317 "data": [
8318 {
8319 "id": "ii_18yKaN2eZvKYlo2Co22dhawI",
8320 "object": "invoiceitem",
8321 "amount": -100,
8322 "currency": "usd",
8323 "customer": "cus_9I1yraWQEUlyFj",
8324 "date": 1474978883,
8325 "description": "Unused time on Foo after 27 Sep 2016",
8326 "discountable": false,
8327 "invoice": "in_18yKaO2eZvKYlo2CXEisc1Ih",
8328 "livemode": false,
8329 "metadata": {
8330 },
8331 "period": {
8332 "start": 1474978883,
8333 "end": 1475583679
8334 },
8335 "plan": {
8336 "id": "16598foo1474978869",
8337 "object": "plan",
8338 "amount": 100,
8339 "created": 1474978873,
8340 "currency": "usd",
8341 "interval": "week",
8342 "interval_count": 1,
8343 "livemode": false,
8344 "metadata": {
8345 },
8346 "name": "Foo",
8347 "statement_descriptor": null,
8348 "trial_period_days": null
8349 },
8350 "proration": true,
8351 "quantity": 1,
8352 "subscription": "sub_9GsKNJuNtntFFH"
8353 },
8354 {...},
8355 {...}
8356 ]
8357 }
8358 }
8359 }
8360}
8361```
8362
8363<a name="createPlan"/>
8364## Stripe.createPlan
8365You 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.
8366
8367| Field | Type | Description
8368|--------------------|------------|----------
8369| apiKey | credentials| The api key obtained from Stripe.
8370| planId | String | 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.
8371| amount | Number | A positive integer in cents (or 0 for a free plan) representing how much to charge (on a recurring basis).
8372| currency | String | 3-letter ISO code for currency.
8373| interval | String | Specifies billing frequency. Either day, week, month or year.
8374| name | String | Name of the plan, to be displayed on invoices and in the web interface.
8375| intervalCount | String | 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).
8376| metadata | String | A set of key/value pairs that you can attach to a plan object. It can be useful for storing additional information about the plan in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
8377| statementDescriptor| String | An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you’re charging for is your Silver Plan, you may want to specify a statement_descriptor of RunClub Silver Plan. The statement description may not include <>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all.
8378| trialPeriodDays | String | 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.
8379
8380#### Request example
8381```json
8382{
8383 "apiKey": "...",
8384 "planId": "gold-extended",
8385 "amount": 5000,
8386 "currency": "usd",
8387 "interval": "month",
8388 "name": "Gold extended",
8389}
8390```
8391#### Response example
8392```json
8393{
8394 "callback":"success",
8395 "contextWrites":{
8396 "#":{
8397 "to": {
8398 "id": "gold-extended",
8399 "object": "plan",
8400 "amount": 5000,
8401 "created": 1475206866,
8402 "currency": "usd",
8403 "interval": "month",
8404 "interval_count": 1,
8405 "livemode": false,
8406 "metadata": {
8407 },
8408 "name": "Gold extended",
8409 "statement_descriptor": null,
8410 "trial_period_days": null
8411 }
8412 }
8413 }
8414}
8415```
8416
8417<a name="getPlan"/>
8418## Stripe.getPlan
8419Retrieves the plan with the given ID.
8420
8421| Field | Type | Description
8422|-------|------------|----------
8423| apiKey| credentials| The api key obtained from Stripe.
8424| planId| String | The ID of the desired plan.
8425
8426#### Request example
8427```json
8428{
8429 "apiKey": "...",
8430 "planId": "..."
8431}
8432```
8433#### Response example
8434```json
8435{
8436 "callback":"success",
8437 "contextWrites":{
8438 "#":{
8439 "to": {
8440 "id": "ivory-starter-327",
8441 "object": "plan",
8442 "amount": 999,
8443 "created": 1475206866,
8444 "currency": "usd",
8445 "interval": "month",
8446 "interval_count": 1,
8447 "livemode": false,
8448 "metadata": {
8449 },
8450 "name": "Ivory Starter",
8451 "statement_descriptor": null,
8452 "trial_period_days": null
8453 }
8454 }
8455 }
8456}
8457```
8458
8459<a name="updatePlan"/>
8460## Stripe.updatePlan
8461Updates the name of a plan. Other plan details (price, interval, etc.) are, by design, not editable.
8462
8463| Field | Type | Description
8464|--------------------|------------|----------
8465| apiKey | credentials| The api key obtained from Stripe.
8466| planId | String | The identifier of the plan to be updated.
8467| name | String | Name of the plan, to be displayed on invoices and in the web interface.
8468| metadata | String | A set of key/value pairs that you can attach to a plan object. It can be useful for storing additional information about the plan in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
8469| statementDescriptor| String | An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you’re charging for is your Silver Plan, you may want to specify a statement_descriptor of RunClub Silver Plan. The statement description may not include <>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all.
8470
8471#### Request example
8472```json
8473{
8474 "apiKey": "...",
8475 "planId": "ivory-starter-327",
8476 "name": "Bronze complete",
8477}
8478```
8479#### Response example
8480```json
8481{
8482 "callback":"success",
8483 "contextWrites":{
8484 "#":{
8485 "to": {
8486 "id": "ivory-starter-327",
8487 "object": "plan",
8488 "amount": 999,
8489 "created": 1475206866,
8490 "currency": "usd",
8491 "interval": "month",
8492 "interval_count": 1,
8493 "livemode": false,
8494 "metadata": {
8495 },
8496 "name": "Bronze complete",
8497 "statement_descriptor": null,
8498 "trial_period_days": null
8499 }
8500 }
8501 }
8502}
8503```
8504
8505<a name="deletePlan"/>
8506## Stripe.deletePlan
8507You 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.
8508
8509| Field | Type | Description
8510|-------|------------|----------
8511| apiKey| credentials| The api key obtained from Stripe.
8512| planId| String | The identifier of the plan to be deleted.
8513
8514#### Request example
8515```json
8516{
8517 "apiKey": "...",
8518 "planId": "ivory-starter-327"
8519}
8520```
8521#### Response example
8522```json
8523{
8524 "callback":"success",
8525 "contextWrites":{
8526 "#":{
8527 "to": {
8528 "deleted": true,
8529 "id": "ivory-starter-327"
8530 }
8531 }
8532 }
8533}
8534```
8535
8536<a name="getPlanList"/>
8537## Stripe.getPlanList
8538Returns a list of your plans.
8539
8540| Field | Type | Description
8541|-------|------------|----------
8542| apiKey| credentials| The api key obtained from Stripe.
8543
8544#### Request example
8545```json
8546{
8547 "apiKey": "...",
8548}
8549```
8550#### Response example
8551```json
8552{
8553 "callback":"success",
8554 "contextWrites":{
8555 "#":{
8556 "to": {
8557 "object": "list",
8558 "url": "/v1/plans",
8559 "has_more": false,
8560 "data": [
8561 {
8562 "id": "ivory-starter-327",
8563 "object": "plan",
8564 "amount": 999,
8565 "created": 1475206866,
8566 "currency": "usd",
8567 "interval": "month",
8568 "interval_count": 1,
8569 "livemode": false,
8570 "metadata": {
8571 },
8572 "name": "Ivory Starter",
8573 "statement_descriptor": null,
8574 "trial_period_days": null
8575 },
8576 {...},
8577 {...}
8578 ]
8579 }
8580 }
8581 }
8582}
8583```
8584
8585<a name="createSubscription"/>
8586## Stripe.createSubscription
8587Creates a new subscription on an existing customer.
8588
8589| Field | Type | Description
8590|----------------------|------------|----------
8591| apiKey | credentials| The api key obtained from Stripe.
8592| applicationFeePercent| String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be transferred to the application owner’s Stripe account. The request must be made with an OAuth key in order to set an application fee percentage.
8593| coupon | String | 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.
8594| customer | String | The identifier of the customer to subscribe.
8595| plan | String | The identifier of the plan to subscribe the customer to.
8596| source | JSON | The source can either be a token, like the ones returned by our Stripe.js, or a object containing a user's credit card details (with the options shown below). You must provide a source if the customer does not already have a valid source attached, and you are subscribing the customer for a plan that is not free. Passing source will create a new source object, make it the customer default source, and delete the old customer default if one exists. If you want to add an additional source to use with subscriptions, instead use the card creation API to add the card and then the customer update API to set it as the default. Whenever you attach a card to a customer, Stripe will automatically validate the card.
8597| quantity | Number | 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.
8598| metadata | JSON | A set of key/value pairs that you can attach to a subscription object. It can be useful for storing additional information about the subscription in a structured format.
8599| taxPercent | String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice.
8600| trialEnd | String | Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately.
8601
8602#### Request example
8603```json
8604{
8605 "apiKey": "...",
8606 "customer": "cus_9HvesRZb9hIG69",
8607 "plan": "ivory-starter-327",
8608}
8609```
8610#### Response example
8611```json
8612{
8613 "callback":"success",
8614 "contextWrites":{
8615 "#":{
8616 "to": {
8617 "id": "sub_9HrdaoU42BIBGY",
8618 "object": "subscription",
8619 "application_fee_percent": null,
8620 "cancel_at_period_end": false,
8621 "canceled_at": null,
8622 "created": 1475206899,
8623 "current_period_end": 1477798899,
8624 "current_period_start": 1475206899,
8625 "customer": "cus_9HvesRZb9hIG69",
8626 "discount": null,
8627 "ended_at": null,
8628 "livemode": false,
8629 "metadata": {
8630 },
8631 "plan": {
8632 "id": "ivory-starter-327",
8633 "object": "plan",
8634 "amount": 999,
8635 "created": 1475206866,
8636 "currency": "usd",
8637 "interval": "month",
8638 "interval_count": 1,
8639 "livemode": false,
8640 "metadata": {
8641 },
8642 "name": "Ivory Starter",
8643 "statement_descriptor": null,
8644 "trial_period_days": null
8645 },
8646 "quantity": 1,
8647 "start": 1475206899,
8648 "status": "active",
8649 "tax_percent": null,
8650 "trial_end": null,
8651 "trial_start": null
8652 }
8653 }
8654 }
8655}
8656```
8657
8658<a name="getSubscription"/>
8659## Stripe.getSubscription
8660Retrieves the subscription with the given ID.
8661
8662| Field | Type | Description
8663|---------------|------------|----------
8664| apiKey | credentials| The api key obtained from Stripe.
8665| subscriptionId| String | ID of subscription to retrieve.
8666
8667#### Request example
8668```json
8669{
8670 "apiKey": "...",
8671 "subscriptionId": "sub_9HrdaoU42BIBGY"
8672}
8673```
8674#### Response example
8675```json
8676{
8677 "callback":"success",
8678 "contextWrites":{
8679 "#":{
8680 "to": {
8681 "id": "sub_9HrdaoU42BIBGY",
8682 "object": "subscription",
8683 "application_fee_percent": null,
8684 "cancel_at_period_end": false,
8685 "canceled_at": null,
8686 "created": 1475206899,
8687 "current_period_end": 1477798899,
8688 "current_period_start": 1475206899,
8689 "customer": "cus_9HrcdqQVqG9h0O",
8690 "discount": null,
8691 "ended_at": null,
8692 "livemode": false,
8693 "metadata": {
8694 },
8695 "plan": {
8696 "id": "ivory-starter-327",
8697 "object": "plan",
8698 "amount": 999,
8699 "created": 1475206866,
8700 "currency": "usd",
8701 "interval": "month",
8702 "interval_count": 1,
8703 "livemode": false,
8704 "metadata": {
8705 },
8706 "name": "Ivory Starter",
8707 "statement_descriptor": null,
8708 "trial_period_days": null
8709 },
8710 "quantity": 1,
8711 "start": 1475206899,
8712 "status": "active",
8713 "tax_percent": null,
8714 "trial_end": null,
8715 "trial_start": null
8716 }
8717 }
8718 }
8719}
8720```
8721
8722<a name="updateSubscription"/>
8723## Stripe.updateSubscription
8724Updates an existing subscription to match the specified parameters. When changing plans or quantities, we will optionally prorate the price we charge next month to make up for any price changes. To preview how the proration will be calculated, use the upcoming invoice endpoint.
8725
8726| Field | Type | Description
8727|----------------------|------------|----------
8728| apiKey | credentials| The api key obtained from Stripe.
8729| subscriptionId | String | ID of subscription to updated.
8730| applicationFeePercent| String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be transferred to the application owner’s Stripe account. The request must be made with an OAuth key in order to set an application fee percentage.
8731| coupon | String | 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.
8732| customer | String | The identifier of the customer to subscribe.
8733| plan | String | The identifier of the plan to subscribe the customer to.
8734| source | JSON | The source can either be a token, like the ones returned by our Stripe.js, or a object containing a user's credit card details (with the options shown below). You must provide a source if the customer does not already have a valid source attached, and you are subscribing the customer for a plan that is not free. Passing source will create a new source object, make it the customer default source, and delete the old customer default if one exists. If you want to add an additional source to use with subscriptions, instead use the card creation API to add the card and then the customer update API to set it as the default. Whenever you attach a card to a customer, Stripe will automatically validate the card.
8735| quantity | Number | 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.
8736| metadata | JSON | A set of key/value pairs that you can attach to a subscription object. It can be useful for storing additional information about the subscription in a structured format.
8737| taxPercent | String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice.
8738| trialEnd | String | Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately.
8739
8740#### Request example
8741```json
8742{
8743 "apiKey": "...",
8744 "subscriptionId": "sub_9HrdaoU42BIBGY",
8745 "plan": "ivory-starter-327",
8746}
8747```
8748#### Response example
8749```json
8750{
8751 "callback":"success",
8752 "contextWrites":{
8753 "#":{
8754 "to": {
8755 "id": "sub_9HrdaoU42BIBGY",
8756 "object": "subscription",
8757 "application_fee_percent": null,
8758 "cancel_at_period_end": false,
8759 "canceled_at": null,
8760 "created": 1475206899,
8761 "current_period_end": 1477798899,
8762 "current_period_start": 1475206899,
8763 "customer": "cus_9HvesRZb9hIG69",
8764 "discount": null,
8765 "ended_at": null,
8766 "livemode": false,
8767 "metadata": {
8768 },
8769 "plan": {
8770 "id": "ivory-starter-327",
8771 "object": "plan",
8772 "amount": 999,
8773 "created": 1475206866,
8774 "currency": "usd",
8775 "interval": "month",
8776 "interval_count": 1,
8777 "livemode": false,
8778 "metadata": {
8779 },
8780 "name": "Ivory Starter",
8781 "statement_descriptor": null,
8782 "trial_period_days": null
8783 },
8784 "quantity": 1,
8785 "start": 1475206899,
8786 "status": "active",
8787 "tax_percent": null,
8788 "trial_end": null,
8789 "trial_start": null
8790 }
8791 }
8792 }
8793}
8794```
8795
8796<a name="cancelSubscription"/>
8797## Stripe.cancelSubscription
8798Cancels 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.
8799By 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.
8800
8801| Field | Type | Description
8802|---------------|------------|----------
8803| apiKey | credentials| The api key obtained from Stripe.
8804| subscriptionId| String | ID of subscription to retrieve.
8805| atPeriodEnd | String | A flag that if set to true will delay the cancellation of the subscription until the end of the current period.
8806
8807#### Request example
8808```json
8809{
8810 "apiKey": "...",
8811 "subscriptionId": "sub_9HrdaoU42BIBGY",
8812}
8813```
8814#### Response example
8815```json
8816{
8817 "callback":"success",
8818 "contextWrites":{
8819 "#":{
8820 "to": {
8821 "id": "sub_9HrdaoU42BIBGY",
8822 "object": "subscription",
8823 "application_fee_percent": null,
8824 "cancel_at_period_end": false,
8825 "canceled_at": null,
8826 "created": 1475206899,
8827 "current_period_end": 1477798899,
8828 "current_period_start": 1475206899,
8829 "customer": "cus_9HvesRZb9hIG69",
8830 "discount": null,
8831 "ended_at": null,
8832 "livemode": false,
8833 "metadata": {
8834 },
8835 "plan": {
8836 "id": "ivory-starter-327",
8837 "object": "plan",
8838 "amount": 999,
8839 "created": 1475206866,
8840 "currency": "usd",
8841 "interval": "month",
8842 "interval_count": 1,
8843 "livemode": false,
8844 "metadata": {
8845 },
8846 "name": "Ivory Starter",
8847 "statement_descriptor": null,
8848 "trial_period_days": null
8849 },
8850 "quantity": 1,
8851 "start": 1475206899,
8852 "status": "canceled",
8853 "tax_percent": null,
8854 "trial_end": null,
8855 "trial_start": null
8856 }
8857 }
8858 }
8859}
8860```
8861
8862<a name="getSubscriptionList"/>
8863## Stripe.getSubscriptionList
8864By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify status=canceled.
8865
8866| Field | Type | Description
8867|---------------|------------|----------
8868| apiKey | credentials| The api key obtained from Stripe.
8869| subscriptionId| String | ID of subscription to retrieve.
8870| customer | String | The ID of the customer whose subscriptions will be retrieved
8871| plan | String | The ID of the plan whose subscriptions will be retrieved
8872| status | String | The status of the subscriptions to retrieve. One of: trialing, active, past_due, unpaid, canceled, or all. Passing in a value of canceled will return all canceled subscriptions, including those belonging to deleted customers. Passing in a value of all will return subscriptions of all statuses.
8873
8874#### Request example
8875```json
8876{
8877 "apiKey": "...",
8878}
8879```
8880#### Response example
8881```json
8882{
8883 "callback":"success",
8884 "contextWrites":{
8885 "#":{
8886 "to":
8887 "object": "list",
8888 "url": "/v1/subscriptions",
8889 "has_more": false,
8890 "data": [
8891 {
8892 "id": "sub_9HrdaoU42BIBGY",
8893 "object": "subscription",
8894 "application_fee_percent": null,
8895 "cancel_at_period_end": false,
8896 "canceled_at": null,
8897 "created": 1475206899,
8898 "current_period_end": 1477798899,
8899 "current_period_start": 1475206899,
8900 "customer": "cus_9HrcdqQVqG9h0O",
8901 "discount": null,
8902 "ended_at": null,
8903 "livemode": false,
8904 "metadata": {
8905 },
8906 "plan": {
8907 "id": "ivory-starter-327",
8908 "object": "plan",
8909 "amount": 999,
8910 "created": 1475206866,
8911 "currency": "usd",
8912 "interval": "month",
8913 "interval_count": 1,
8914 "livemode": false,
8915 "metadata": {
8916 },
8917 "name": "Ivory Starter",
8918 "statement_descriptor": null,
8919 "trial_period_days": null
8920 },
8921 "quantity": 1,
8922 "start": 1475206899,
8923 "status": "active",
8924 "tax_percent": null,
8925 "trial_end": null,
8926 "trial_start": null
8927 },
8928 {...},
8929 {...}
8930 ]
8931 }
8932 }
8933 }
8934}
8935```
8936
8937
8938
8939<a name="createTransferReversal"/>
8940## Stripe.createTransferReversal
8941Method description
8942
8943| Field | Type | Description
8944|---------------------|------------|----------
8945| apiKey | credentials| The api key obtained from Stripe.
8946| transferId | credentials| The identifier of the transfer to be reversed.
8947| description | String | An arbitrary string which you can attach to a reversal object. It is displayed alongside the reversal in the dashboard. This will be unset if you POST an empty value.
8948| metadata | String | A set of key/value pairs that you can attach to a reversal object. It can be useful for storing additional information about the reversal in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
8949| refundApplicationFee| String | Boolean indicating whether the application fee should be refunded when reversing this transfer. If a full transfer reversal is given, the full application fee will be refunded. Otherwise, the application fee will be refunded with an amount proportional to the amount of the transfer reversed.
8950
8951#### Request example
8952```json
8953{ "apiKey": "...",
8954 "transferId": "...",
8955 "description": "...",
8956 "metadata": "...",
8957 "refundApplicationFee": "..."
8958}
8959```
8960#### Response example
8961```json
8962{
8963 "callback":"success",
8964 "contextWrites":{
8965 "#":{
8966 "to":"..."
8967 }
8968 }
8969}
8970```
8971
8972<a name="getTransferReversal"/>
8973## Stripe.getTransferReversal
8974Method description
8975
8976| Field | Type | Description
8977|-----------|------------|----------
8978| apiKey | credentials| The api key obtained from Stripe.
8979| id | String | ID of reversal to retrieve.
8980| transferId| String | ID of the transfer reversed.
8981
8982#### Request example
8983```json
8984{ "apiKey": "...",
8985 "id": "...",
8986 "transferId": "..."
8987}
8988```
8989#### Response example
8990```json
8991{
8992 "callback":"success",
8993 "contextWrites":{
8994 "#":{
8995 "to":"..."
8996 }
8997 }
8998}
8999```
9000
9001<a name="updateTransferReversal"/>
9002## Stripe.updateTransferReversal
9003Method description
9004
9005| Field | Type | Description
9006|------------|------------|----------
9007| apiKey | credentials| The api key obtained from Stripe.
9008| id | String | ID of reversal to retrieve.
9009| transferId | String | ID of the transfer reversed.
9010| metadata | JSON | A set of key/value pairs that you can attach to a reversal object. It can be useful for storing additional information about the reversal in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
9011| description| String | An arbitrary string which you can attach to a reversal object. It is displayed when in the web interface alongside the reversal. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
9012
9013#### Request example
9014```json
9015{ "apiKey": "...",
9016 "id": "...",
9017 "transferId": "...",
9018 "metadata": "...",
9019 "description": "..."
9020}
9021```
9022#### Response example
9023```json
9024{
9025 "callback":"success",
9026 "contextWrites":{
9027 "#":{
9028 "to":"..."
9029 }
9030 }
9031}
9032```
9033
9034<a name="getTransferReversalList"/>
9035## Stripe.getTransferReversalList
9036Method description
9037
9038| Field | Type | Description
9039|-----------|------------|----------
9040| apiKey | credentials| The api key obtained from Stripe.
9041| transferId| String | The ID of the transfer whose reversals will be retrieved.
9042
9043#### Request example
9044```json
9045{ "apiKey": "...",
9046 "transferId": "..."
9047}
9048```
9049#### Response example
9050```json
9051{
9052 "callback":"success",
9053 "contextWrites":{
9054 "#":{
9055 "to":"..."
9056 }
9057 }
9058}
9059```
9060
9061<a name="createAccount"/>
9062## Stripe.createAccount
9063Method description
9064
9065| Field | Type | Description
9066|--------|------------|----------
9067| apiKey | credentials| The api key obtained from Stripe.
9068| country| String | The country the account holder resides in or that the business is legally established in. For example, if you are in the United States and the business you’re creating an account for is legally represented in Canada, you would use “CA†as the country for the account being created.
9069| email | String | The email address of the account holder. For standalone accounts, Stripe will email your user with instructions for how to set up their account. For managed accounts, this is only to make the account easier to identify to you: Stripe will never directly reach out to your users.
9070| managed| String | Whether you'd like to create a managed or standalone account. Managed accounts have extra parameters available to them, and require that you, the platform, handle all communication with the account holder. Standalone accounts are normal Stripe accounts: Stripe will email the account holder to setup a username and password, and handle all account management directly with them.
9071
9072#### Request example
9073```json
9074{ "apiKey": "...",
9075 "country": "...",
9076 "email": "...",
9077 "managed": "..."
9078}
9079```
9080#### Response example
9081```json
9082{
9083 "callback":"success",
9084 "contextWrites":{
9085 "#":{
9086 "to":"..."
9087 }
9088 }
9089}
9090```
9091
9092<a name="getAccount"/>
9093## Stripe.getAccount
9094Method description
9095
9096| Field | Type | Description
9097|----------|------------|----------
9098| apiKey | credentials| The api key obtained from Stripe.
9099| accountId| String | Id of account to retrive
9100
9101#### Request example
9102```json
9103{ "apiKey": "...",
9104 "accountId": "..."
9105}
9106```
9107#### Response example
9108```json
9109{
9110 "callback":"success",
9111 "contextWrites":{
9112 "#":{
9113 "to":"..."
9114 }
9115 }
9116}
9117```
9118
9119<a name="updateAccount"/>
9120## Stripe.updateAccount
9121Method description
9122
9123| Field | Type | Description
9124|----------------------|------------|----------
9125| apiKey | credentials| The api key obtained from Stripe.
9126| accountId | String | Id of account to update
9127| businessLogo | String | Bussines logo
9128| businessName | String | The publicly sharable name for this account.
9129| businessPrimaryColor | String | A CSS hex color value representing the primary branding color for this account
9130| businessUrl | String | The URL that best shows the service or product provided for this account
9131| debitNegativeBalances| String | A boolean for whether or not Stripe should try to reclaim negative balances from the account holder’s bank account.
9132| declineChargeOn | String | Account-level settings to automatically decline certain types of charges regardless of the bank’s decision.
9133| defaultCurrency | String | Three-letter ISO currency code representing the default currency for the account.
9134| email | String | Email address of the account holder. For standalone accounts, this is used to email them asking them to claim their Stripe account. For managed accounts, this is only to make the account easier to identify to you: Stripe will not email the account holder.
9135| externalAccount | String | A card or bank account to attach to the account. You can provide either a token, like the ones returned by Stripe.js, or a dictionary as documented in the external_account parameter for either card or bank account creation.
9136| legalEntity | String | Information about the account holder; varies by account country and account status.
9137| metadata | JSON | A set of key/value pairs that you can attach to an account object. It can be useful for storing additional information about the account in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
9138| productDescription | String | Internal-only description of the product being sold or service being provided by this account. It’s used by Stripe for risk and underwriting purposes.
9139| statementDescriptor | String | The text that will appear on credit card statements by default if a charge is being made directly on the account.
9140| supportEmail | String | A publicly shareable email address that can be reached for support for this account
9141| supportPhone | String | A publicly shareable phone number that can be reached for support for this account
9142| supportUrl | String | A publicly shareable URL that can be reached for support for this account
9143| tosAcceptance | JSON | Details on who accepted the Stripe terms of service, and when they accepted it
9144| transferSchedule | JSON | Details on when this account will make funds from charges available, and when they will be paid out to the account holder’s bank account.
9145
9146#### Request example
9147```json
9148{ "apiKey": "...",
9149 "accountId": "...",
9150 "businessLogo": "...",
9151 "businessName": "...",
9152 "businessPrimaryColor": "...",
9153 "businessUrl": "...",
9154 "debitNegativeBalances": "...",
9155 "declineChargeOn": "...",
9156 "defaultCurrency": "...",
9157 "email": "...",
9158 "externalAccount": "...",
9159 "legalEntity": "...",
9160 "metadata": "...",
9161 "productDescription": "...",
9162 "statementDescriptor": "...",
9163 "supportEmail": "...",
9164 "supportPhone": "...",
9165 "supportUrl": "...",
9166 "tosAcceptance": "...",
9167 "transferSchedule": "..."
9168}
9169```
9170#### Response example
9171```json
9172{
9173 "callback":"success",
9174 "contextWrites":{
9175 "#":{
9176 "to":"..."
9177 }
9178 }
9179}
9180```
9181
9182<a name="deleteAccount"/>
9183## Stripe.deleteAccount
9184Method description
9185
9186| Field | Type | Description
9187|----------|------------|----------
9188| apiKey | credentials| The api key obtained from Stripe.
9189| accountId| String | Id of account to delete
9190
9191#### Request example
9192```json
9193{ "apiKey": "...",
9194 "accountId": "..."
9195}
9196```
9197#### Response example
9198```json
9199{
9200 "callback":"success",
9201 "contextWrites":{
9202 "#":{
9203 "to":"..."
9204 }
9205 }
9206}
9207```
9208
9209<a name="rejectAccount"/>
9210## Stripe.rejectAccount
9211Method description
9212
9213| Field | Type | Description
9214|----------|------------|----------
9215| apiKey | credentials| The api key obtained from Stripe.
9216| accountId| String | Id of account to reject
9217| reason | String | The reason for rejecting the account. May be one of `fraud`, `terms_of_service`, or `other`.
9218
9219#### Request example
9220```json
9221{ "apiKey": "...",
9222 "accountId": "...",
9223 "reason": "..."
9224}
9225```
9226#### Response example
9227```json
9228{
9229 "callback":"success",
9230 "contextWrites":{
9231 "#":{
9232 "to":"..."
9233 }
9234 }
9235}
9236```
9237
9238<a name="getAccountList"/>
9239## Stripe.getAccountList
9240Method description
9241
9242| Field | Type | Description
9243|--------------|------------|----------
9244| apiKey | credentials| The api key obtained from Stripe.
9245| endingBefore | String | 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.
9246| limit | Number | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
9247| startingAfter| String | 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.
9248
9249#### Request example
9250```json
9251{ "apiKey": "...",
9252 "endingBefore": "...",
9253 "limit": 0,
9254 "startingAfter": "..."
9255}
9256```
9257#### Response example
9258```json
9259{
9260 "callback":"success",
9261 "contextWrites":{
9262 "#":{
9263 "to":"..."
9264 }
9265 }
9266}
9267```
9268
9269<a name="createFeeRefund"/>
9270## Stripe.createFeeRefund
9271Method description
9272
9273| Field | Type | Description
9274|---------|------------|----------
9275| apiKey | credentials| The api key obtained from Stripe.
9276| appId | String | The identifier of the application fee to be refunded.
9277| amount | Number | A positive integer in cents representing how much of this fee to refund. Can only refund up to the unrefunded amount remaining of the fee.
9278| metadata| JSON | A set of key/value pairs that you can attach to a refund object. It can be useful for storing additional information about the refund in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
9279
9280#### Request example
9281```json
9282{ "apiKey": "...",
9283 "appId": "...",
9284 "amount": 0,
9285 "metadata": "..."
9286}
9287```
9288#### Response example
9289```json
9290{
9291 "callback":"success",
9292 "contextWrites":{
9293 "#":{
9294 "to":"..."
9295 }
9296 }
9297}
9298```
9299
9300<a name="getFeeRefund"/>
9301## Stripe.getFeeRefund
9302Method description
9303
9304| Field | Type | Description
9305|---------|------------|----------
9306| apiKey | credentials| The api key obtained from Stripe.
9307| feeId | String | ID of the application fee refunded.
9308| refundId| String | ID of refund to retrieve.
9309
9310#### Request example
9311```json
9312{ "apiKey": "...",
9313 "feeId": "...",
9314 "refundId": "..."
9315}
9316```
9317#### Response example
9318```json
9319{
9320 "callback":"success",
9321 "contextWrites":{
9322 "#":{
9323 "to":"..."
9324 }
9325 }
9326}
9327```
9328
9329<a name="updateFeeRefund"/>
9330## Stripe.updateFeeRefund
9331Method description
9332
9333| Field | Type | Description
9334|---------|------------|----------
9335| apiKey | credentials| The api key obtained from Stripe.
9336| feeId | String | ID of the application fee refunded.
9337| refundId| String | ID of refund to retrieve.
9338| metadata| JSON | A set of key/value pairs that you can attach to an application fee refund object. It can be useful for storing additional information about the refund in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null, then save.
9339
9340#### Request example
9341```json
9342{ "apiKey": "...",
9343 "feeId": "...",
9344 "refundId": "...",
9345 "metadata": "..."
9346}
9347```
9348#### Response example
9349```json
9350{
9351 "callback":"success",
9352 "contextWrites":{
9353 "#":{
9354 "to":"..."
9355 }
9356 }
9357}
9358```
9359
9360<a name="getFeeRefundList"/>
9361## Stripe.getFeeRefundList
9362Method description
9363
9364| Field | Type | Description
9365|--------------|------------|----------
9366| apiKey | credentials| The api key obtained from Stripe.
9367| appId | String | The ID of the application fee whose refunds will be retrieved.
9368| endingBefore | String | 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.
9369| limit | Number | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
9370| startingAfter| String | 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.
9371
9372#### Request example
9373```json
9374{ "apiKey": "...",
9375 "appId": "...",
9376 "endingBefore": "...",
9377 "limit": 0,
9378 "startingAfter": "..."
9379}
9380```
9381#### Response example
9382```json
9383{
9384 "callback":"success",
9385 "contextWrites":{
9386 "#":{
9387 "to":"..."
9388 }
9389 }
9390}
9391```
9392
9393<a name="getApplicationFee"/>
9394## Stripe.getApplicationFee
9395Method description
9396
9397| Field | Type | Description
9398|-------|------------|----------
9399| apiKey| credentials| The api key obtained from Stripe.
9400| feeId | String | The identifier of the fee to be retrieved.
9401
9402#### Request example
9403```json
9404{ "apiKey": "...",
9405 "feeId": "..."
9406}
9407```
9408#### Response example
9409```json
9410{
9411 "callback":"success",
9412 "contextWrites":{
9413 "#":{
9414 "to":"..."
9415 }
9416 }
9417}
9418```
9419
9420<a name="getApplicationFeeList"/>
9421## Stripe.getApplicationFeeList
9422Method description
9423
9424| Field | Type | Description
9425|--------------|------------|----------
9426| apiKey | credentials| The api key obtained from Stripe.
9427| chargeId | String | Only return application fees for the charge specified by this charge ID.
9428| endingBefore | String | 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.
9429| limit | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
9430| startingAfter| String | 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.
9431
9432#### Request example
9433```json
9434{ "apiKey": "...",
9435 "chargeId": "...",
9436 "endingBefore": "...",
9437 "limit": "...",
9438 "startingAfter": "..."
9439}
9440```
9441#### Response example
9442```json
9443{
9444 "callback":"success",
9445 "contextWrites":{
9446 "#":{
9447 "to":"..."
9448 }
9449 }
9450}
9451```
9452
9453<a name="getCountrySpecsList"/>
9454## Stripe.getCountrySpecsList
9455Method description
9456
9457| Field | Type | Description
9458|--------------|------------|----------
9459| apiKey | credentials| The api key obtained from Stripe.
9460| endingBefore | String | 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.
9461| limit | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
9462| startingAfter| String | 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.
9463
9464#### Request example
9465```json
9466{ "apiKey": "...",
9467 "endingBefore": "...",
9468 "limit": "...",
9469 "startingAfter": "..."
9470}
9471```
9472#### Response example
9473```json
9474{
9475 "callback":"success",
9476 "contextWrites":{
9477 "#":{
9478 "to":"..."
9479 }
9480 }
9481}
9482```
9483
9484<a name="getCountrySpec"/>
9485## Stripe.getCountrySpec
9486Method description
9487
9488| Field | Type | Description
9489|--------|------------|----------
9490| apiKey | credentials| The api key obtained from Stripe.
9491| country| String | An ISO country code. Available country codes can be listed with the List Country Specs endpoint.
9492
9493#### Request example
9494```json
9495{ "apiKey": "...",
9496 "country": "..."
9497}
9498```
9499#### Response example
9500```json
9501{
9502 "callback":"success",
9503 "contextWrites":{
9504 "#":{
9505 "to":"..."
9506 }
9507 }
9508}
9509```
9510
9511<a name="createBankAccount"/>
9512## Stripe.createBankAccount
9513Method description
9514
9515| Field | Type | Description
9516|-------------------|------------|----------
9517| apiKey | credentials| The api key obtained from Stripe.
9518| accountId | String | The account ID obtained from Stripe.
9519| source | String | When adding a bank account to a customer, the parameter name is source. When adding to an account, the parameter name is external_account. The value can either be a token, like the ones returned by Stripe.js, or a dictionary containing a user’s bank account details (with the options shown below).
9520| externalAccount | String | When adding a bank account to a customer, the parameter name is source. When adding to an account, the parameter name is external_account. The value can either be a token, like the ones returned by Stripe.js, or a dictionary containing a user’s bank account details (with the options shown below).
9521| defaultForCurrency| String | If you set this to true (or if this is the first bank account being added in this currency) this bank account will become the default bank account for its currency.
9522| metadata | JSON | A set of key/value pairs that you can attach to an external account object. It can be useful for storing additional information about the external account in a structured format.
9523
9524#### Request example
9525```json
9526{ "apiKey": "...",
9527 "accountId": "...",
9528 "source": "...",
9529 "externalAccount": "...",
9530 "defaultForCurrency": "...",
9531 "metadata": "..."
9532}
9533```
9534#### Response example
9535```json
9536{
9537 "callback":"success",
9538 "contextWrites":{
9539 "#":{
9540 "to":"..."
9541 }
9542 }
9543}
9544```
9545
9546<a name="getBankAccount"/>
9547## Stripe.getBankAccount
9548Method description
9549
9550| Field | Type | Description
9551|--------------|------------|----------
9552| apiKey | credentials| The api key obtained from Stripe.
9553| accountId | String | The account ID obtained from Stripe.
9554| bankAccountId| String | The bank account ID obtained from Stripe.
9555
9556#### Request example
9557```json
9558{ "apiKey": "...",
9559 "accountId": "...",
9560 "bankAccountId": "..."
9561}
9562```
9563#### Response example
9564```json
9565{
9566 "callback":"success",
9567 "contextWrites":{
9568 "#":{
9569 "to":"..."
9570 }
9571 }
9572}
9573```
9574
9575<a name="updateBankAccount"/>
9576## Stripe.updateBankAccount
9577Method description
9578
9579| Field | Type | Description
9580|--------------|------------|----------
9581| apiKey | credentials| The api key obtained from Stripe.
9582| accountId | String | The account ID obtained from Stripe.
9583| bankAccountId| String | The ID of the bank account to be updated.
9584| metadata | JSON | A set of key/value pairs that you can attach to an external account object. It can be useful for storing additional information about the external account in a structured format.
9585
9586#### Request example
9587```json
9588{ "apiKey": "...",
9589 "accountId": "...",
9590 "bankAccountId": "...",
9591 "metadata": "..."
9592}
9593```
9594#### Response example
9595```json
9596{
9597 "callback":"success",
9598 "contextWrites":{
9599 "#":{
9600 "to":"..."
9601 }
9602 }
9603}
9604```
9605
9606<a name="deleteBankAccount"/>
9607## Stripe.deleteBankAccount
9608Method description
9609
9610| Field | Type | Description
9611|--------------|------------|----------
9612| apiKey | credentials| The api key obtained from Stripe.
9613| accountId | String | The account ID obtained from Stripe.
9614| bankAccountId| String | The bank account ID obtained from Stripe.
9615
9616#### Request example
9617```json
9618{ "apiKey": "...",
9619 "accountId": "...",
9620 "bankAccountId": "..."
9621}
9622```
9623#### Response example
9624```json
9625{
9626 "callback":"success",
9627 "contextWrites":{
9628 "#":{
9629 "to":"..."
9630 }
9631 }
9632}
9633```
9634
9635<a name="getBankAccountList"/>
9636## Stripe.getBankAccountList
9637Method description
9638
9639| Field | Type | Description
9640|--------------|------------|----------
9641| apiKey | credentials| The api key obtained from Stripe.
9642| accountId | String | The account ID obtained from Stripe.
9643| endingBefore | String | 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.
9644| limit | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
9645| startingAfter| String | 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.
9646
9647#### Request example
9648```json
9649{ "apiKey": "...",
9650 "accountId": "...",
9651 "endingBefore": "...",
9652 "limit": "...",
9653 "startingAfter": "..."
9654}
9655```
9656#### Response example
9657```json
9658{
9659 "callback":"success",
9660 "contextWrites":{
9661 "#":{
9662 "to":"..."
9663 }
9664 }
9665}
9666```
9667
9668<a name="createCard"/>
9669## Stripe.createCard
9670Method description
9671
9672| Field | Type | Description
9673|-------------------|------------|----------
9674| apiKey | credentials| The api key obtained from Stripe.
9675| accountId | String | The account ID obtained from Stripe.
9676| source | String | When adding a bank account to a customer, the parameter name is source. When adding to an account, the parameter name is external_account. The value can either be a token, like the ones returned by Stripe.js, or a dictionary containing a user’s bank account details (with the options shown below).
9677| externalAccount | String | When adding a bank account to a customer, the parameter name is source. When adding to an account, the parameter name is external_account. The value can either be a token, like the ones returned by Stripe.js, or a dictionary containing a user’s bank account details (with the options shown below).
9678| defaultForCurrency| String | If you set this to true (or if this is the first bank account being added in this currency) this bank account will become the default bank account for its currency.
9679| metadata | JSON | A set of key/value pairs that you can attach to an external account object. It can be useful for storing additional information about the external account in a structured format.
9680
9681#### Request example
9682```json
9683{ "apiKey": "...",
9684 "accountId": "...",
9685 "source": "...",
9686 "externalAccount": "...",
9687 "defaultForCurrency": "...",
9688 "metadata": "..."
9689}
9690```
9691#### Response example
9692```json
9693{
9694 "callback":"success",
9695 "contextWrites":{
9696 "#":{
9697 "to":"..."
9698 }
9699 }
9700}
9701```
9702
9703<a name="getCard"/>
9704## Stripe.getCard
9705Method description
9706
9707| Field | Type | Description
9708|----------|------------|----------
9709| apiKey | credentials| The api key obtained from Stripe.
9710| accountId| String | The account ID obtained from Stripe.
9711| cardId | String | The card ID obtained from Stripe.
9712
9713#### Request example
9714```json
9715{ "apiKey": "...",
9716 "accountId": "...",
9717 "cardId": "..."
9718}
9719```
9720#### Response example
9721```json
9722{
9723 "callback":"success",
9724 "contextWrites":{
9725 "#":{
9726 "to":"..."
9727 }
9728 }
9729}
9730```
9731
9732<a name="updateCard"/>
9733## Stripe.updateCard
9734Method description
9735
9736| Field | Type | Description
9737|-------------------|------------|----------
9738| apiKey | credentials| The api key obtained from Stripe.
9739| accountId | String | The account ID obtained from Stripe.
9740| cardId | String | The card ID obtained from Stripe.
9741| addressCity | String | City.
9742| addressCountry | String | Country.
9743| addressLine1 | String | Line 1.
9744| addressLine2 | String | Line 2.
9745| addressState | String | State.
9746| addressZip | String | State.
9747| defaultForCurrency| String | Only applicable on accounts (not customers or recipients). If set to true, this card will become the default external account for its currency..
9748| expMonth | String | Month.
9749| expYear | String | Year.
9750| metadata | String | 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 null and then saving.
9751| name | String | Name.
9752
9753#### Request example
9754```json
9755{ "apiKey": "...",
9756 "accountId": "...",
9757 "cardId": "...",
9758 "addressCity": "...",
9759 "addressCountry": "...",
9760 "addressLine1": "...",
9761 "addressLine2": "...",
9762 "addressState": "...",
9763 "addressZip": "...",
9764 "defaultForCurrency": "...",
9765 "expMonth": "...",
9766 "expYear": "...",
9767 "metadata": "...",
9768 "name": "..."
9769}
9770```
9771#### Response example
9772```json
9773{
9774 "callback":"success",
9775 "contextWrites":{
9776 "#":{
9777 "to":"..."
9778 }
9779 }
9780}
9781```
9782
9783<a name="deleteCard"/>
9784## Stripe.deleteCard
9785Method description
9786
9787| Field | Type | Description
9788|----------|------------|----------
9789| apiKey | credentials| The api key obtained from Stripe.
9790| accountId| String | The account ID obtained from Stripe.
9791| cardId | String | The card ID obtained from Stripe.
9792
9793#### Request example
9794```json
9795{ "apiKey": "...",
9796 "accountId": "...",
9797 "cardId": "..."
9798}
9799```
9800#### Response example
9801```json
9802{
9803 "callback":"success",
9804 "contextWrites":{
9805 "#":{
9806 "to":"..."
9807 }
9808 }
9809}
9810```
9811
9812<a name="getCardList"/>
9813## Stripe.getCardList
9814Method description
9815
9816| Field | Type | Description
9817|--------------|------------|----------
9818| apiKey | credentials| The api key obtained from Stripe.
9819| accountId | String | The account ID obtained from Stripe.
9820| endingBefore | String | 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.
9821| limit | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
9822| startingAfter| String | 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.
9823
9824#### Request example
9825```json
9826{ "apiKey": "...",
9827 "accountId": "...",
9828 "endingBefore": "...",
9829 "limit": "...",
9830 "startingAfter": "..."
9831}
9832```
9833#### Response example
9834```json
9835{
9836 "callback":"success",
9837 "contextWrites":{
9838 "#":{
9839 "to":"..."
9840 }
9841 }
9842}
9843```
9844
9845<a name="createReceiver"/>
9846## Stripe.createReceiver
9847Method description
9848
9849| Field | Type | Description
9850|------------------|------------|----------
9851| apiKey | credentials| The api key obtained from Stripe.
9852| amount | String | The account ID obtained from Stripe.
9853| currency | String | Only USD currently supported
9854| email | String | 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.
9855| description | String | A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
9856| metadata | String |
9857| refundMispayments| String |
9858
9859#### Request example
9860```json
9861{ "apiKey": "...",
9862 "amount": "...",
9863 "currency": "...",
9864 "email": "...",
9865 "description": "...",
9866 "metadata": "...",
9867 "refundMispayments": "..."
9868}
9869```
9870#### Response example
9871```json
9872{
9873 "callback":"success",
9874 "contextWrites":{
9875 "#":{
9876 "to":"..."
9877 }
9878 }
9879}
9880```
9881
9882<a name="getReceiver"/>
9883## Stripe.getReceiver
9884Method description
9885
9886| Field | Type | Description
9887|-----------|------------|----------
9888| apiKey | credentials| The api key obtained from Stripe.
9889| receiverId| String | Id of receiver to retrive.
9890
9891#### Request example
9892```json
9893{ "apiKey": "...",
9894 "receiverId": "..."
9895}
9896```
9897#### Response example
9898```json
9899{
9900 "callback":"success",
9901 "contextWrites":{
9902 "#":{
9903 "to":"..."
9904 }
9905 }
9906}
9907```
9908
9909<a name="getReceiverList"/>
9910## Stripe.getReceiverList
9911Method description
9912
9913| Field | Type | Description
9914|-------|------------|----------
9915| apiKey| credentials| The api key obtained from Stripe.
9916
9917#### Request example
9918```json
9919{ "apiKey": "..."
9920}
9921```
9922#### Response example
9923```json
9924{
9925 "callback":"success",
9926 "contextWrites":{
9927 "#":{
9928 "to":"..."
9929 }
9930 }
9931}
9932```
9933
9934<a name="createOrder"/>
9935## Stripe.createOrder
9936Method description
9937
9938| Field | Type | Description
9939|---------|------------|----------
9940| apiKey | credentials| The api key obtained from Stripe.
9941| currency| String | 3-letter ISO code representing the currency in which the order should be made. Stripe will validate that all entries in items match the currency specified here.
9942| coupon | String | A coupon code that represents a discount to be applied to this order. Must be one-time duration and in same currency as the order.
9943| customer| String | The ID of an existing customer to use for this order. If provided, the customer email and shipping address will be used to create the order. Subsequently, the customer will also be charged to pay the order. If email or shipping are also provided, they will override the values retrieved from the customer object.
9944| email | String | The email address of the customer placing the order.
9945| items | JSON | List of items constituting the order.
9946| metadata| JSON | A set of key/value pairs that you can attach to an order object. It can be useful for storing additional information about the order in a structured format.
9947| shipping| JSON | Shipping address for the order. Required if any of the SKUs are for products that have shippable set to true.
9948
9949#### Request example
9950```json
9951{ "apiKey": "...",
9952 "currency": "...",
9953 "coupon": "...",
9954 "customer": "...",
9955 "email": "...",
9956 "items": "...",
9957 "metadata": "...",
9958 "shipping": "..."
9959}
9960```
9961#### Response example
9962```json
9963{
9964 "callback":"success",
9965 "contextWrites":{
9966 "#":{
9967 "to":"..."
9968 }
9969 }
9970}
9971```
9972
9973<a name="getOrder"/>
9974## Stripe.getOrder
9975Method description
9976
9977| Field | Type | Description
9978|--------|------------|----------
9979| apiKey | credentials| The api key obtained from Stripe.
9980| orderId| String | Id of receiver to retrive.
9981
9982#### Request example
9983```json
9984{ "apiKey": "...",
9985 "orderId": "..."
9986}
9987```
9988#### Response example
9989```json
9990{
9991 "callback":"success",
9992 "contextWrites":{
9993 "#":{
9994 "to":"..."
9995 }
9996 }
9997}
9998```
9999
10000<a name="updateOrder"/>
10001## Stripe.updateOrder
10002Method description
10003
10004| Field | Type | Description
10005|---------|------------|----------
10006| apiKey | credentials| The api key obtained from Stripe.
10007| orderId | credentials| Id of order to update.
10008| coupon | String | A coupon code that represents a discount to be applied to this order. Must be one-time duration and in same currency as the order.
10009| metadata| JSON | A set of key/value pairs that you can attach to an order object. It can be useful for storing additional information about the order in a structured format.
10010| shipping| JSON | Shipping address for the order. Required if any of the SKUs are for products that have shippable set to true.
10011| status | credentials| Current order status. One of `created`, `paid`, `canceled`, `fulfilled`, or `returned`.
10012
10013#### Request example
10014```json
10015{ "apiKey": "...",
10016 "orderId": "...",
10017 "coupon": "...",
10018 "metadata": "...",
10019 "shipping": "...",
10020 "status": "..."
10021}
10022```
10023#### Response example
10024```json
10025{
10026 "callback":"success",
10027 "contextWrites":{
10028 "#":{
10029 "to":"..."
10030 }
10031 }
10032}
10033```
10034
10035<a name="payOrder"/>
10036## Stripe.payOrder
10037Method description
10038
10039| Field | Type | Description
10040|---------|------------|----------
10041| apiKey | credentials| The api key obtained from Stripe.
10042| orderId | String | The ID of an order to pay.
10043| customer| String | The ID of an existing customer that will be charged in this request.
10044| source | String | A payment source to be charged, such as a credit card. If you also pass a customer ID, the source must be the ID of a source belonging to the customer. Otherwise, if you do not pass a customer ID, the source you provide must either be a token, like the ones returned by Stripe.js, or a object containing a user's credit card details, with the options described below. Although not all information is required, the extra info helps prevent fraud.
10045| metadata| JSON | A set of key/value pairs that you can attach to an order object. It can be useful for storing additional information about the order in a structured format.
10046| email | String | The email address of the customer placing the order. If a customer is specified, that customer's email address will be used.
10047
10048#### Request example
10049```json
10050{ "apiKey": "...",
10051 "orderId": "...",
10052 "customer": "...",
10053 "source": "...",
10054 "metadata": "...",
10055 "email": "..."
10056}
10057```
10058#### Response example
10059```json
10060{
10061 "callback":"success",
10062 "contextWrites":{
10063 "#":{
10064 "to":"..."
10065 }
10066 }
10067}
10068```
10069
10070<a name="getOrderList"/>
10071## Stripe.getOrderList
10072Method description
10073
10074| Field | Type | Description
10075|------------------|------------|----------
10076| apiKey | credentials| The api key obtained from Stripe.
10077| created | String | A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:
10078| customer | String | Only return orders for the given customer.
10079| ids | String | Only return orders with the given IDs.
10080| status | String | Only return orders that have the given status. One of `created`, `paid`, `fulfilled`, or `refunded`.
10081| statusTransitions| String | Filter orders based on when they were paid, fulfilled, canceled, or returned.
10082| upstreamIds | String | Only return orders with the given upstream order IDs.
10083
10084#### Request example
10085```json
10086{ "apiKey": "...",
10087 "created": "...",
10088 "customer": "...",
10089 "ids": "...",
10090 "status": "...",
10091 "statusTransitions": "...",
10092 "upstreamIds": "..."
10093}
10094```
10095#### Response example
10096```json
10097{
10098 "callback":"success",
10099 "contextWrites":{
10100 "#":{
10101 "to":"..."
10102 }
10103 }
10104}
10105```
10106
10107<a name="returnOrder"/>
10108## Stripe.returnOrder
10109Method description
10110
10111| Field | Type | Description
10112|--------|------------|----------
10113| apiKey | credentials| The api key obtained from Stripe.
10114| orderId| JSON | Order id.
10115| items | JSON | List of items to return.
10116
10117#### Request example
10118```json
10119{ "apiKey": "...",
10120 "orderId": "...",
10121 "items": "..."
10122}
10123```
10124#### Response example
10125```json
10126{
10127 "callback":"success",
10128 "contextWrites":{
10129 "#":{
10130 "to":"..."
10131 }
10132 }
10133}
10134```
10135
10136<a name="getOrderReturn"/>
10137## Stripe.getOrderReturn
10138Method description
10139
10140| Field | Type | Description
10141|--------|------------|----------
10142| apiKey | credentials| The api key obtained from Stripe.
10143| orderId| JSON | The identifier of the order return to be retrieved.
10144
10145#### Request example
10146```json
10147{ "apiKey": "...",
10148 "orderId": "..."
10149}
10150```
10151#### Response example
10152```json
10153{
10154 "callback":"success",
10155 "contextWrites":{
10156 "#":{
10157 "to":"..."
10158 }
10159 }
10160}
10161```
10162
10163<a name="getOrderReturnList"/>
10164## Stripe.getOrderReturnList
10165Method description
10166
10167| Field | Type | Description
10168|--------|------------|----------
10169| apiKey | credentials| The api key obtained from Stripe.
10170| created| String | A filter on the list based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:
10171| order | String | The order to retrieve returns for.
10172
10173#### Request example
10174```json
10175{ "apiKey": "...",
10176 "created": "...",
10177 "order": "..."
10178}
10179```
10180#### Response example
10181```json
10182{
10183 "callback":"success",
10184 "contextWrites":{
10185 "#":{
10186 "to":"..."
10187 }
10188 }
10189}
10190```
10191
10192<a name="createProduct"/>
10193## Stripe.createProduct
10194Method description
10195
10196| Field | Type | Description
10197|------------------|------------|----------
10198| apiKey | credentials| The api key obtained from Stripe.
10199| name | String | The product’s name, meant to be displayable to the customer.
10200| active | String | Whether or not the product is currently available for purchase. Defaults to `true`.
10201| attributes | JSON | A list of up to 5 alphanumeric attributes that each SKU can provide values for (e.g. `["color", "size"]`).
10202| caption | String | A short one-line description of the product, meant to be displayable to the customer.
10203| deactivateOn | JSON | An array of Connect application names or identifiers that should not be able to order the SKUs for this product.
10204| description | String | The product’s description, meant to be displayable to the customer.
10205| images | JSON | A list of up to 8 URLs of images for this product, meant to be displayable to the customer.
10206| metadata | JSON | A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format.
10207| packageDimensions| String | The dimensions of this product for shipping purposes. A SKU associated with this product can override this value by having its own package_dimensions.
10208| shippable | String | Whether this product is shipped (i.e. physical goods). Defaults to true.
10209| url | String | A URL of a publicly-accessible webpage for this product.
10210
10211#### Request example
10212```json
10213{ "apiKey": "...",
10214 "name": "...",
10215 "active": "...",
10216 "attributes": "...",
10217 "caption": "...",
10218 "deactivateOn": "...",
10219 "description": "...",
10220 "images": "...",
10221 "metadata": "...",
10222 "packageDimensions": "...",
10223 "shippable": "...",
10224 "url": "..."
10225}
10226```
10227#### Response example
10228```json
10229{
10230 "callback":"success",
10231 "contextWrites":{
10232 "#":{
10233 "to":"..."
10234 }
10235 }
10236}
10237```
10238
10239<a name="getProduct"/>
10240## Stripe.getProduct
10241Method description
10242
10243| Field | Type | Description
10244|----------|------------|----------
10245| apiKey | credentials| The api key obtained from Stripe.
10246| productId| String | The identifier of the product to be retrieved.
10247
10248#### Request example
10249```json
10250{ "apiKey": "...",
10251 "productId": "..."
10252}
10253```
10254#### Response example
10255```json
10256{
10257 "callback":"success",
10258 "contextWrites":{
10259 "#":{
10260 "to":"..."
10261 }
10262 }
10263}
10264```
10265
10266<a name="updateProduct"/>
10267## Stripe.updateProduct
10268Method description
10269
10270| Field | Type | Description
10271|------------------|------------|----------
10272| apiKey | credentials| The api key obtained from Stripe.
10273| productId | String | The id of product to update.
10274| name | String | The product’s name, meant to be displayable to the customer.
10275| active | String | Whether or not the product is currently available for purchase. Defaults to `true`.
10276| attributes | JSON | A list of up to 5 alphanumeric attributes that each SKU can provide values for (e.g. `["color", "size"]`).
10277| caption | String | A short one-line description of the product, meant to be displayable to the customer.
10278| deactivateOn | JSON | An array of Connect application names or identifiers that should not be able to order the SKUs for this product.
10279| description | String | The product’s description, meant to be displayable to the customer.
10280| images | JSON | A list of up to 8 URLs of images for this product, meant to be displayable to the customer.
10281| metadata | JSON | A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format.
10282| packageDimensions| String | The dimensions of this product for shipping purposes. A SKU associated with this product can override this value by having its own package_dimensions.
10283| shippable | String | Whether this product is shipped (i.e. physical goods). Defaults to true.
10284| url | String | A URL of a publicly-accessible webpage for this product.
10285
10286#### Request example
10287```json
10288{ "apiKey": "...",
10289 "productId": "...",
10290 "name": "...",
10291 "active": "...",
10292 "attributes": "...",
10293 "caption": "...",
10294 "deactivateOn": "...",
10295 "description": "...",
10296 "images": "...",
10297 "metadata": "...",
10298 "packageDimensions": "...",
10299 "shippable": "...",
10300 "url": "..."
10301}
10302```
10303#### Response example
10304```json
10305{
10306 "callback":"success",
10307 "contextWrites":{
10308 "#":{
10309 "to":"..."
10310 }
10311 }
10312}
10313```
10314
10315<a name="getProductList"/>
10316## Stripe.getProductList
10317Method description
10318
10319| Field | Type | Description
10320|----------|------------|----------
10321| apiKey | credentials| The api key obtained from Stripe.
10322| ids | String | Only return products with the given IDs.
10323| shippable| String | Only return products that can be shipped (i.e., physical, not digital products).
10324| url | String | Only return products with the given url.
10325
10326#### Request example
10327```json
10328{ "apiKey": "...",
10329 "ids": "...",
10330 "shippable": "...",
10331 "url": "..."
10332}
10333```
10334#### Response example
10335```json
10336{
10337 "callback":"success",
10338 "contextWrites":{
10339 "#":{
10340 "to":"..."
10341 }
10342 }
10343}
10344```
10345
10346<a name="deleteProduct"/>
10347## Stripe.deleteProduct
10348Method description
10349
10350| Field | Type | Description
10351|----------|------------|----------
10352| apiKey | credentials| The api key obtained from Stripe.
10353| productId| String | The ID of the product to delete.
10354
10355#### Request example
10356```json
10357{ "apiKey": "...",
10358 "productId": "..."
10359}
10360```
10361#### Response example
10362```json
10363{
10364 "callback":"success",
10365 "contextWrites":{
10366 "#":{
10367 "to":"..."
10368 }
10369 }
10370}
10371```
10372
10373<a name="createSKU"/>
10374## Stripe.createSKU
10375Method description
10376
10377| Field | Type | Description
10378|------------------|------------|----------
10379| apiKey | credentials| The api key obtained from Stripe.
10380| currency | String | 3-letter ISO code for currency.
10381| inventory | String | Description of the SKU’s inventory.
10382| price | Number | The cost of the item as a nonnegative integer in the smallest currency unit (that is, 100 cents to charge $1.00, or 100 to charge ¥100, Japanese Yen being a 0-decimal currency).
10383| product | String | The ID of the product this SKU is associated with.
10384| active | String | Whether or not the SKU is available for purchase. Default to true.
10385| attributes | JSON | A dictionary of attributes and values for the attributes defined by the product. If, for example, a product’s attributes are ["size", "gender"], a valid SKU has the following dictionary of attributes: {"size": "Medium", "gender": "Unisex"}.
10386| image | String | The URL of an image for this SKU, meant to be displayable to the customer.
10387| metadata | JSON | A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format.
10388| packageDimensions| JSON | The dimensions of this SKU for shipping purposes.
10389
10390#### Request example
10391```json
10392{ "apiKey": "...",
10393 "currency": "...",
10394 "inventory": "...",
10395 "price": 0,
10396 "product": "...",
10397 "active": "...",
10398 "attributes": "...",
10399 "image": "...",
10400 "metadata": "...",
10401 "packageDimensions": "..."
10402}
10403```
10404#### Response example
10405```json
10406{
10407 "callback":"success",
10408 "contextWrites":{
10409 "#":{
10410 "to":"..."
10411 }
10412 }
10413}
10414```
10415
10416<a name="getSKU"/>
10417## Stripe.getSKU
10418Method description
10419
10420| Field | Type | Description
10421|-------|------------|----------
10422| apiKey| credentials| The api key obtained from Stripe.
10423| skuId | String | The identifier of the SKU to be retrieved.
10424
10425#### Request example
10426```json
10427{ "apiKey": "...",
10428 "skuId": "..."
10429}
10430```
10431#### Response example
10432```json
10433{
10434 "callback":"success",
10435 "contextWrites":{
10436 "#":{
10437 "to":"..."
10438 }
10439 }
10440}
10441```
10442
10443<a name="updateSKU"/>
10444## Stripe.updateSKU
10445Method description
10446
10447| Field | Type | Description
10448|------------------|------------|----------
10449| apiKey | credentials| The api key obtained from Stripe.
10450| skuId | String | The identifier of the SKU to be updated.
10451| currency | String | 3-letter ISO code for currency.
10452| inventory | String | Description of the SKU’s inventory.
10453| price | String | The cost of the item as a nonnegative integer in the smallest currency unit (that is, 100 cents to charge $1.00, or 100 to charge ¥100, Japanese Yen being a 0-decimal currency).
10454| product | String | The ID of the product this SKU is associated with.
10455| active | String | Whether or not the SKU is available for purchase. Default to true.
10456| attributes | JSON | A dictionary of attributes and values for the attributes defined by the product. If, for example, a product’s attributes are ["size", "gender"], a valid SKU has the following dictionary of attributes: {"size": "Medium", "gender": "Unisex"}.
10457| image | String | The URL of an image for this SKU, meant to be displayable to the customer.
10458| metadata | JSON | A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format.
10459| packageDimensions| JSON | The dimensions of this SKU for shipping purposes.
10460
10461#### Request example
10462```json
10463{ "apiKey": "...",
10464 "skuId": "...",
10465 "currency": "...",
10466 "inventory": "...",
10467 "price": "...",
10468 "product": "...",
10469 "active": "...",
10470 "attributes": "...",
10471 "image": "...",
10472 "metadata": "...",
10473 "packageDimensions": "..."
10474}
10475```
10476#### Response example
10477```json
10478{
10479 "callback":"success",
10480 "contextWrites":{
10481 "#":{
10482 "to":"..."
10483 }
10484 }
10485}
10486```
10487
10488<a name="getSKUList"/>
10489## Stripe.getSKUList
10490Method description
10491
10492| Field | Type | Description
10493|-----------|------------|----------
10494| apiKey | credentials| The api key obtained from Stripe.
10495| attributes| String |
10496| ids | String | Only return SKUs with the given IDs.
10497| productId | String | The ID of the product whose SKUs will be retrieved.
10498
10499#### Request example
10500```json
10501{ "apiKey": "...",
10502 "attributes": "...",
10503 "ids": "...",
10504 "productId": "..."
10505}
10506```
10507#### Response example
10508```json
10509{
10510 "callback":"success",
10511 "contextWrites":{
10512 "#":{
10513 "to":"..."
10514 }
10515 }
10516}
10517```
10518
10519<a name="deleteSKU"/>
10520## Stripe.deleteSKU
10521Method description
10522
10523| Field | Type | Description
10524|-------|------------|----------
10525| apiKey| credentials| The api key obtained from Stripe.
10526| skuId | String | The identifier of the SKU to be deleted.
10527
10528#### Request example
10529```json
10530{ "apiKey": "...",
10531 "skuId": "..."
10532}
10533```
10534#### Response example
10535```json
10536{
10537 "callback":"success",
10538 "contextWrites":{
10539 "#":{
10540 "to":"..."
10541 }
10542 }
10543}
10544```
10545
10546<a name="createCoupon"/>
10547## Stripe.createCoupon
10548Method description
10549
10550| Field | Type | Description
10551|-----------------|------------|----------
10552| apiKey | credentials| The api key obtained from Stripe.
10553| couponId | String | Unique string of your choice that will be used to identify this coupon when applying it to a customer. This is often a specific code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you can leave the ID blank and we’ll generate a random code for you.
10554| duration | String | Specifies how long the discount will be in effect. Can be `forever`, `once`, or `repeating`.
10555| amountOff | String | A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed)
10556| currency | String | Currency of the amount_off parameter (required if amount_off is passed)
10557| durationInMonths| String | Required only if duration is repeating, in which case it must be a positive integer that specifies the number of months the discount will be in effect.
10558| maxRedemptions | String | 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.
10559| metadata | JSON | 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 null and then saving.
10560| percentOff | String | A positive integer between 1 and 100 that represents the discount the coupon will apply (required if amount_off is not passed)
10561| redeemBy | String | Unix timestamp specifying the last time at which the coupon can be redeemed. After the redeem_by date, the coupon can no longer be applied to new customers.
10562
10563#### Request example
10564```json
10565{ "apiKey": "...",
10566 "couponId": "...",
10567 "duration": "...",
10568 "amountOff": "...",
10569 "currency": "...",
10570 "durationInMonths": "...",
10571 "maxRedemptions": "...",
10572 "metadata": "...",
10573 "percentOff": "...",
10574 "redeemBy": "..."
10575}
10576```
10577#### Response example
10578```json
10579{
10580 "callback":"success",
10581 "contextWrites":{
10582 "#":{
10583 "to":"..."
10584 }
10585 }
10586}
10587```
10588
10589<a name="getCoupon"/>
10590## Stripe.getCoupon
10591Method description
10592
10593| Field | Type | Description
10594|---------|------------|----------
10595| apiKey | credentials| The api key obtained from Stripe.
10596| couponId| String | Unique string of your choice that will be used to identify this coupon when applying it to a customer. This is often a specific code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you can leave the ID blank and we’ll generate a random code for you.
10597
10598#### Request example
10599```json
10600{ "apiKey": "...",
10601 "couponId": "..."
10602}
10603```
10604#### Response example
10605```json
10606{
10607 "callback":"success",
10608 "contextWrites":{
10609 "#":{
10610 "to":"..."
10611 }
10612 }
10613}
10614```
10615
10616<a name="updateCoupon"/>
10617## Stripe.updateCoupon
10618Method description
10619
10620| Field | Type | Description
10621|---------|------------|----------
10622| apiKey | credentials| The api key obtained from Stripe.
10623| couponId| String | Unique string of your choice that will be used to identify this coupon when applying it to a customer. This is often a specific code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you can leave the ID blank and we’ll generate a random code for you.
10624| metadata| JSON | 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 null and then saving.
10625
10626#### Request example
10627```json
10628{ "apiKey": "...",
10629 "couponId": "...",
10630 "metadata": "..."
10631}
10632```
10633#### Response example
10634```json
10635{
10636 "callback":"success",
10637 "contextWrites":{
10638 "#":{
10639 "to":"..."
10640 }
10641 }
10642}
10643```
10644
10645<a name="deleteCoupon"/>
10646## Stripe.deleteCoupon
10647Method description
10648
10649| Field | Type | Description
10650|---------|------------|----------
10651| apiKey | credentials| The api key obtained from Stripe.
10652| couponId| String | Unique string of your choice that will be used to identify this coupon when applying it to a customer. This is often a specific code you’ll give to your customer to use when signing up (e.g. FALL25OFF). If you don’t want to specify a particular code, you can leave the ID blank and we’ll generate a random code for you.
10653
10654#### Request example
10655```json
10656{ "apiKey": "...",
10657 "couponId": "..."
10658}
10659```
10660#### Response example
10661```json
10662{
10663 "callback":"success",
10664 "contextWrites":{
10665 "#":{
10666 "to":"..."
10667 }
10668 }
10669}
10670```
10671
10672<a name="getCouponList"/>
10673## Stripe.getCouponList
10674Method description
10675
10676| Field | Type | Description
10677|-------|------------|----------
10678| apiKey| credentials| The api key obtained from Stripe.
10679
10680#### Request example
10681```json
10682{ "apiKey": "..."
10683}
10684```
10685#### Response example
10686```json
10687{
10688 "callback":"success",
10689 "contextWrites":{
10690 "#":{
10691 "to":"..."
10692 }
10693 }
10694}
10695```
10696
10697<a name="deleteCustomerDiscount"/>
10698## Stripe.deleteCustomerDiscount
10699Method description
10700
10701| Field | Type | Description
10702|-----------|------------|----------
10703| apiKey | credentials| The api key obtained from Stripe.
10704| customerId| String | Id of customer to delete.
10705
10706#### Request example
10707```json
10708{ "apiKey": "...",
10709 "customerId": "..."
10710}
10711```
10712#### Response example
10713```json
10714{
10715 "callback":"success",
10716 "contextWrites":{
10717 "#":{
10718 "to":"..."
10719 }
10720 }
10721}
10722```
10723
10724<a name="deleteSubscriptionDiscount"/>
10725## Stripe.deleteSubscriptionDiscount
10726Method description
10727
10728| Field | Type | Description
10729|---------------|------------|----------
10730| apiKey | credentials| The api key obtained from Stripe.
10731| subscriptionId| String | Id of subscribtion to delete.
10732
10733#### Request example
10734```json
10735{ "apiKey": "...",
10736 "subscriptionId": "..."
10737}
10738```
10739#### Response example
10740```json
10741{
10742 "callback":"success",
10743 "contextWrites":{
10744 "#":{
10745 "to":"..."
10746 }
10747 }
10748}
10749```
10750
10751<a name="createInvoice"/>
10752## Stripe.createInvoice
10753Method description
10754
10755| Field | Type | Description
10756|--------------------|------------|----------
10757| apiKey | credentials| The api key obtained from Stripe.
10758| customer | String | Customer Id
10759| applicationFee | String | A fee in cents that will be applied to the invoice and transferred to the application owner’s Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee.
10760| description | String | 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.
10761| metadata | JSON | 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 null and then saving.
10762| statementDescriptor| String | Extra information about a charge for the customer’s credit card statement.
10763| subscription | String | The ID of the subscription to invoice. If not set, the created invoice will include all pending invoice items for the customer. If set, the created invoice will exclude pending invoice items that pertain to other subscriptions.
10764| taxPercent | String | The percent tax rate applied to the invoice, represented as a decimal number.
10765
10766#### Request example
10767```json
10768{ "apiKey": "...",
10769 "customer": "...",
10770 "applicationFee": "...",
10771 "description": "...",
10772 "metadata": "...",
10773 "statementDescriptor": "...",
10774 "subscription": "...",
10775 "taxPercent": "..."
10776}
10777```
10778#### Response example
10779```json
10780{
10781 "callback":"success",
10782 "contextWrites":{
10783 "#":{
10784 "to":"..."
10785 }
10786 }
10787}
10788```
10789
10790<a name="getInvoice"/>
10791## Stripe.getInvoice
10792Method description
10793
10794| Field | Type | Description
10795|----------|------------|----------
10796| apiKey | credentials| The api key obtained from Stripe.
10797| invoiceId| String | Invoice id.
10798
10799#### Request example
10800```json
10801{ "apiKey": "...",
10802 "invoiceId": "..."
10803}
10804```
10805#### Response example
10806```json
10807{
10808 "callback":"success",
10809 "contextWrites":{
10810 "#":{
10811 "to":"..."
10812 }
10813 }
10814}
10815```
10816
10817<a name="getInvoiceLineItems"/>
10818## Stripe.getInvoiceLineItems
10819Method description
10820
10821| Field | Type | Description
10822|--------------------------|------------|----------
10823| apiKey | credentials| The api key obtained from Stripe.
10824| invoice | String | Invoice id.
10825| coupon | String | Counpon id.
10826| customer | String | In the case of upcoming invoices, the customer of the upcoming invoice is required. In other cases it is ignored.
10827| subscription | String | In the case of upcoming invoices, the subscription of the upcoming invoice is optional. In other cases it is ignored.
10828| subscriptionPlan | String | Subscription Plan
10829| subscriptionProrate | String | Subscription Prorate
10830| subscriptionProrationDate| String | Subscription Proration Date
10831| subscriptionQuantity | String | Subscription Quantity
10832| subscriptionTrialEnd | String | Subscription Trial End
10833
10834#### Request example
10835```json
10836{ "apiKey": "...",
10837 "invoice": "...",
10838 "coupon": "...",
10839 "customer": "...",
10840 "subscription": "...",
10841 "subscriptionPlan": "...",
10842 "subscriptionProrate": "...",
10843 "subscriptionProrationDate": "...",
10844 "subscriptionQuantity": "...",
10845 "subscriptionTrialEnd": "..."
10846}
10847```
10848#### Response example
10849```json
10850{
10851 "callback":"success",
10852 "contextWrites":{
10853 "#":{
10854 "to":"..."
10855 }
10856 }
10857}
10858```
10859
10860<a name="updateInvoice"/>
10861## Stripe.updateInvoice
10862Method description
10863
10864| Field | Type | Description
10865|--------------------|------------|----------
10866| apiKey | credentials| The api key obtained from Stripe.
10867| invoiceId | String | Invoice id.
10868| applicationFee | String | A fee in cents that will be applied to the invoice and transferred to the application owner’s Stripe account. The request must be made with an OAuth key or the Stripe-Account header in order to take an application fee.
10869| description | String | 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.
10870| metadata | String | 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 null and then saving.
10871| statementDescriptor| String | Extra information about a charge for the customer’s credit card statement.
10872| subscription | String | The ID of the subscription to invoice. If not set, the created invoice will include all pending invoice items for the customer. If set, the created invoice will exclude pending invoice items that pertain to other subscriptions.
10873| forgiven | String | Boolean representing whether an invoice is forgiven or not. To forgive an invoice, pass true. Forgiving an invoice instructs us to update the subscription status as if the invoice were successfully paid. Once an invoice has been forgiven, it cannot be unforgiven or reopened.
10874| closed | String | Boolean representing whether an invoice is closed or not. To close an invoice, pass true.
10875| taxPercent | String | The percent tax rate applied to the invoice, represented as a decimal number.
10876
10877#### Request example
10878```json
10879{ "apiKey": "...",
10880 "invoiceId": "...",
10881 "applicationFee": "...",
10882 "description": "...",
10883 "metadata": "...",
10884 "statementDescriptor": "...",
10885 "subscription": "...",
10886 "forgiven": "...",
10887 "closed": "...",
10888 "taxPercent": "..."
10889}
10890```
10891#### Response example
10892```json
10893{
10894 "callback":"success",
10895 "contextWrites":{
10896 "#":{
10897 "to":"..."
10898 }
10899 }
10900}
10901```
10902
10903<a name="payInvoice"/>
10904## Stripe.payInvoice
10905Method description
10906
10907| Field | Type | Description
10908|----------|------------|----------
10909| apiKey | credentials| The api key obtained from Stripe.
10910| invoiceId| String | Invoice id.
10911
10912#### Request example
10913```json
10914{ "apiKey": "...",
10915 "invoiceId": "..."
10916}
10917```
10918#### Response example
10919```json
10920{
10921 "callback":"success",
10922 "contextWrites":{
10923 "#":{
10924 "to":"..."
10925 }
10926 }
10927}
10928```
10929
10930<a name="getInvoiceList"/>
10931## Stripe.getInvoiceList
10932Method description
10933
10934| Field | Type | Description
10935|---------|------------|----------
10936| apiKey | credentials| The api key obtained from Stripe.
10937| customer| String | The identifier of the customer whose invoices to return. If none is provided, all invoices will be returned.
10938
10939#### Request example
10940```json
10941{ "apiKey": "...",
10942 "customer": "..."
10943}
10944```
10945#### Response example
10946```json
10947{
10948 "callback":"success",
10949 "contextWrites":{
10950 "#":{
10951 "to":"..."
10952 }
10953 }
10954}
10955```
10956
10957<a name="getInvoiceList"/>
10958## Stripe.getInvoiceList
10959Method description
10960
10961| Field | Type | Description
10962|---------|------------|----------
10963| apiKey | credentials| The api key obtained from Stripe.
10964| customer| String | The identifier of the customer whose invoices to return. If none is provided, all invoices will be returned.
10965
10966#### Request example
10967```json
10968{ "apiKey": "...",
10969 "customer": "..."
10970}
10971```
10972#### Response example
10973```json
10974{
10975 "callback":"success",
10976 "contextWrites":{
10977 "#":{
10978 "to":"..."
10979 }
10980 }
10981}
10982```
10983
10984<a name="createInvoiceItem"/>
10985## Stripe.createInvoiceItem
10986Method description
10987
10988| Field | Type | Description
10989|-------------|------------|----------
10990| apiKey | credentials| The api key obtained from Stripe.
10991| amount | Number | 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.
10992| currency | String | 3-letter ISO code for currency.
10993| customer | String | The ID of the customer who will be billed when this invoice item is billed.
10994| description | String | 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 null and then saving.
10995| discountable| String | Controls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items.
10996| invoice | String | The ID of an existing invoice to add this invoice item to. When left blank, the invoice item will be added to the next upcoming scheduled invoice. Use this when adding invoice items in response to an invoice.created webhook. You cannot add an invoice item to an invoice that has already been paid, attempted or closed.
10997| metadata | JSON | A set of key/value pairs that you can attach to an invoice item object. It can be useful for storing additional information about the invoice item in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
10998| subscription| String | 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.
10999
11000#### Request example
11001```json
11002{ "apiKey": "...",
11003 "amount": 0,
11004 "currency": "...",
11005 "customer": "...",
11006 "description": "...",
11007 "discountable": "...",
11008 "invoice": "...",
11009 "metadata": "...",
11010 "subscription": "..."
11011}
11012```
11013#### Response example
11014```json
11015{
11016 "callback":"success",
11017 "contextWrites":{
11018 "#":{
11019 "to":"..."
11020 }
11021 }
11022}
11023```
11024
11025<a name="getInvoiceItem"/>
11026## Stripe.getInvoiceItem
11027Method description
11028
11029| Field | Type | Description
11030|------------|------------|----------
11031| apiKey | credentials| The api key obtained from Stripe.
11032| invoiceitem| String | The ID of the desired invoice item.
11033
11034#### Request example
11035```json
11036{ "apiKey": "...",
11037 "invoiceitem": "..."
11038}
11039```
11040#### Response example
11041```json
11042{
11043 "callback":"success",
11044 "contextWrites":{
11045 "#":{
11046 "to":"..."
11047 }
11048 }
11049}
11050```
11051
11052<a name="updateInvoiceItem"/>
11053## Stripe.updateInvoiceItem
11054Method description
11055
11056| Field | Type | Description
11057|-------------|------------|----------
11058| apiKey | credentials| The api key obtained from Stripe.
11059| itemId | String | Item id.
11060| amount | Number | 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.
11061| description | String | 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 null and then saving.
11062| discountable| String | Controls whether discounts apply to this invoice item. Defaults to false for prorations or negative invoice items, and true for all other invoice items. Cannot be set to true for prorations.
11063| metadata | JSON | 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 null and then saving. To clear all keys, set metadata to null, then save.
11064
11065#### Request example
11066```json
11067{ "apiKey": "...",
11068 "itemId": "...",
11069 "amount": 0,
11070 "description": "...",
11071 "discountable": "...",
11072 "metadata": "..."
11073}
11074```
11075#### Response example
11076```json
11077{
11078 "callback":"success",
11079 "contextWrites":{
11080 "#":{
11081 "to":"..."
11082 }
11083 }
11084}
11085```
11086
11087<a name="deleteInvoiceItem"/>
11088## Stripe.deleteInvoiceItem
11089Method description
11090
11091| Field | Type | Description
11092|------------|------------|----------
11093| apiKey | credentials| The api key obtained from Stripe.
11094| invoiceitem| String | The ID of the desired invoice item.
11095
11096#### Request example
11097```json
11098{ "apiKey": "...",
11099 "invoiceitem": "..."
11100}
11101```
11102#### Response example
11103```json
11104{
11105 "callback":"success",
11106 "contextWrites":{
11107 "#":{
11108 "to":"..."
11109 }
11110 }
11111}
11112```
11113
11114<a name="getInvoiceItemsList"/>
11115## Stripe.getInvoiceItemsList
11116Method description
11117
11118| Field | Type | Description
11119|---------|------------|----------
11120| apiKey | credentials| The api key obtained from Stripe.
11121| customer| String | The identifier of the customer whose invoice items to return. If none is provided, all invoice items will be returned.
11122
11123#### Request example
11124```json
11125{ "apiKey": "...",
11126 "customer": "..."
11127}
11128```
11129#### Response example
11130```json
11131{
11132 "callback":"success",
11133 "contextWrites":{
11134 "#":{
11135 "to":"..."
11136 }
11137 }
11138}
11139```
11140
11141<a name="createPlan"/>
11142## Stripe.createPlan
11143Method description
11144
11145| Field | Type | Description
11146|--------------------|------------|----------
11147| apiKey | credentials| The api key obtained from Stripe.
11148| planId | String | 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.
11149| amount | String | A positive integer in cents (or 0 for a free plan) representing how much to charge (on a recurring basis).
11150| currency | String | 3-letter ISO code for currency.
11151| interval | String | Specifies billing frequency. Either day, week, month or year.
11152| name | String | Name of the plan, to be displayed on invoices and in the web interface.
11153| intervalCount | String | 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).
11154| metadata | String | A set of key/value pairs that you can attach to a plan object. It can be useful for storing additional information about the plan in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
11155| statementDescriptor| String | An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you’re charging for is your Silver Plan, you may want to specify a statement_descriptor of RunClub Silver Plan. The statement description may not include <>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all.
11156| trialPeriodDays | String | 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.
11157
11158#### Request example
11159```json
11160{ "apiKey": "...",
11161 "planId": "...",
11162 "amount": "...",
11163 "currency": "...",
11164 "interval": "...",
11165 "name": "...",
11166 "intervalCount": "...",
11167 "metadata": "...",
11168 "statementDescriptor": "...",
11169 "trialPeriodDays": "..."
11170}
11171```
11172#### Response example
11173```json
11174{
11175 "callback":"success",
11176 "contextWrites":{
11177 "#":{
11178 "to":"..."
11179 }
11180 }
11181}
11182```
11183
11184<a name="getPlan"/>
11185## Stripe.getPlan
11186Method description
11187
11188| Field | Type | Description
11189|-------|------------|----------
11190| apiKey| credentials| The api key obtained from Stripe.
11191| planId| String | The ID of the desired plan.
11192
11193#### Request example
11194```json
11195{ "apiKey": "...",
11196 "planId": "..."
11197}
11198```
11199#### Response example
11200```json
11201{
11202 "callback":"success",
11203 "contextWrites":{
11204 "#":{
11205 "to":"..."
11206 }
11207 }
11208}
11209```
11210
11211<a name="updatePlan"/>
11212## Stripe.updatePlan
11213Method description
11214
11215| Field | Type | Description
11216|--------------------|------------|----------
11217| apiKey | credentials| The api key obtained from Stripe.
11218| planId | String | The identifier of the plan to be updated.
11219| name | String | Name of the plan, to be displayed on invoices and in the web interface.
11220| metadata | String | A set of key/value pairs that you can attach to a plan object. It can be useful for storing additional information about the plan in a structured format. This will be unset if you POST an empty value.This can be unset by updating the value to null and then saving.
11221| statementDescriptor| String | An arbitrary string to be displayed on your customer’s credit card statement. This may be up to 22 characters. As an example, if your website is RunClub and the item you’re charging for is your Silver Plan, you may want to specify a statement_descriptor of RunClub Silver Plan. The statement description may not include <>"' characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. While most banks display this information consistently, some may display it incorrectly or not at all.
11222
11223#### Request example
11224```json
11225{ "apiKey": "...",
11226 "planId": "...",
11227 "name": "...",
11228 "metadata": "...",
11229 "statementDescriptor": "..."
11230}
11231```
11232#### Response example
11233```json
11234{
11235 "callback":"success",
11236 "contextWrites":{
11237 "#":{
11238 "to":"..."
11239 }
11240 }
11241}
11242```
11243
11244<a name="deletePlan"/>
11245## Stripe.deletePlan
11246Method description
11247
11248| Field | Type | Description
11249|-------|------------|----------
11250| apiKey| credentials| The api key obtained from Stripe.
11251| planId| String | The identifier of the plan to be deleted.
11252
11253#### Request example
11254```json
11255{ "apiKey": "...",
11256 "planId": "..."
11257}
11258```
11259#### Response example
11260```json
11261{
11262 "callback":"success",
11263 "contextWrites":{
11264 "#":{
11265 "to":"..."
11266 }
11267 }
11268}
11269```
11270
11271<a name="getPlanList"/>
11272## Stripe.getPlanList
11273Method description
11274
11275| Field | Type | Description
11276|-------|------------|----------
11277| apiKey| credentials| The api key obtained from Stripe.
11278
11279#### Request example
11280```json
11281{ "apiKey": "..."
11282}
11283```
11284#### Response example
11285```json
11286{
11287 "callback":"success",
11288 "contextWrites":{
11289 "#":{
11290 "to":"..."
11291 }
11292 }
11293}
11294```
11295
11296<a name="createSubscription"/>
11297## Stripe.createSubscription
11298Method description
11299
11300| Field | Type | Description
11301|----------------------|------------|----------
11302| apiKey | credentials| The api key obtained from Stripe.
11303| applicationFeePercent| String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be transferred to the application owner’s Stripe account. The request must be made with an OAuth key in order to set an application fee percentage.
11304| coupon | String | 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.
11305| customer | String | The identifier of the customer to subscribe.
11306| plan | String | The identifier of the plan to subscribe the customer to.
11307| source | JSON | The source can either be a token, like the ones returned by our Stripe.js, or a object containing a user's credit card details (with the options shown below). You must provide a source if the customer does not already have a valid source attached, and you are subscribing the customer for a plan that is not free. Passing source will create a new source object, make it the customer default source, and delete the old customer default if one exists. If you want to add an additional source to use with subscriptions, instead use the card creation API to add the card and then the customer update API to set it as the default. Whenever you attach a card to a customer, Stripe will automatically validate the card.
11308| quantity | Number | 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.
11309| metadata | JSON | A set of key/value pairs that you can attach to a subscription object. It can be useful for storing additional information about the subscription in a structured format.
11310| taxPercent | String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice.
11311| trialEnd | String | Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately.
11312
11313#### Request example
11314```json
11315{ "apiKey": "...",
11316 "applicationFeePercent": "...",
11317 "coupon": "...",
11318 "customer": "...",
11319 "plan": "...",
11320 "source": "...",
11321 "quantity": 0,
11322 "metadata": "...",
11323 "taxPercent": "...",
11324 "trialEnd": "..."
11325}
11326```
11327#### Response example
11328```json
11329{
11330 "callback":"success",
11331 "contextWrites":{
11332 "#":{
11333 "to":"..."
11334 }
11335 }
11336}
11337```
11338
11339<a name="getSubscription"/>
11340## Stripe.getSubscription
11341Method description
11342
11343| Field | Type | Description
11344|---------------|------------|----------
11345| apiKey | credentials| The api key obtained from Stripe.
11346| subscriptionId| String | ID of subscription to retrieve.
11347
11348#### Request example
11349```json
11350{ "apiKey": "...",
11351 "subscriptionId": "..."
11352}
11353```
11354#### Response example
11355```json
11356{
11357 "callback":"success",
11358 "contextWrites":{
11359 "#":{
11360 "to":"..."
11361 }
11362 }
11363}
11364```
11365
11366<a name="updateSubscription"/>
11367## Stripe.updateSubscription
11368Method description
11369
11370| Field | Type | Description
11371|----------------------|------------|----------
11372| apiKey | credentials| The api key obtained from Stripe.
11373| subscriptionId | String | ID of subscription to updated.
11374| applicationFeePercent| String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be transferred to the application owner’s Stripe account. The request must be made with an OAuth key in order to set an application fee percentage.
11375| coupon | String | 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.
11376| customer | String | The identifier of the customer to subscribe.
11377| plan | String | The identifier of the plan to subscribe the customer to.
11378| source | JSON | The source can either be a token, like the ones returned by our Stripe.js, or a object containing a user's credit card details (with the options shown below). You must provide a source if the customer does not already have a valid source attached, and you are subscribing the customer for a plan that is not free. Passing source will create a new source object, make it the customer default source, and delete the old customer default if one exists. If you want to add an additional source to use with subscriptions, instead use the card creation API to add the card and then the customer update API to set it as the default. Whenever you attach a card to a customer, Stripe will automatically validate the card.
11379| quantity | Number | 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.
11380| metadata | JSON | A set of key/value pairs that you can attach to a subscription object. It can be useful for storing additional information about the subscription in a structured format.
11381| taxPercent | String | A positive decimal (with at most four decimal places) between 1 and 100. This represents the percentage of the subscription invoice subtotal that will be calculated and added as tax to the final amount each billing period. For example, a plan which charges $10/month with a tax_percent of 20.0 will charge $12 per invoice.
11382| trialEnd | String | Unix timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value now can be provided to end the customer's trial immediately.
11383
11384#### Request example
11385```json
11386{ "apiKey": "...",
11387 "subscriptionId": "...",
11388 "applicationFeePercent": "...",
11389 "coupon": "...",
11390 "customer": "...",
11391 "plan": "...",
11392 "source": "...",
11393 "quantity": 0,
11394 "metadata": "...",
11395 "taxPercent": "...",
11396 "trialEnd": "..."
11397}
11398```
11399#### Response example
11400```json
11401{
11402 "callback":"success",
11403 "contextWrites":{
11404 "#":{
11405 "to":"..."
11406 }
11407 }
11408}
11409```
11410
11411<a name="cancelSubscription"/>
11412## Stripe.cancelSubscription
11413Method description
11414
11415| Field | Type | Description
11416|---------------|------------|----------
11417| apiKey | credentials| The api key obtained from Stripe.
11418| subscriptionId| String | ID of subscription to retrieve.
11419| atPeriodEnd | String | A flag that if set to true will delay the cancellation of the subscription until the end of the current period.
11420
11421#### Request example
11422```json
11423{ "apiKey": "...",
11424 "subscriptionId": "...",
11425 "atPeriodEnd": "..."
11426}
11427```
11428#### Response example
11429```json
11430{
11431 "callback":"success",
11432 "contextWrites":{
11433 "#":{
11434 "to":"..."
11435 }
11436 }
11437}
11438```
11439
11440<a name="getSubscriptionList"/>
11441## Stripe.getSubscriptionList
11442Method description
11443
11444| Field | Type | Description
11445|---------------|------------|----------
11446| apiKey | credentials| The api key obtained from Stripe.
11447| subscriptionId| String | ID of subscription to retrieve.
11448| customer | String | The ID of the customer whose subscriptions will be retrieved
11449| plan | String | The ID of the plan whose subscriptions will be retrieved
11450| status | String | The status of the subscriptions to retrieve. One of: trialing, active, past_due, unpaid, canceled, or all. Passing in a value of canceled will return all canceled subscriptions, including those belonging to deleted customers. Passing in a value of all will return subscriptions of all statuses.
11451
11452#### Request example
11453```json
11454{ "apiKey": "...",
11455 "subscriptionId": "...",
11456 "customer": "...",
11457 "plan": "...",
11458 "status": "..."
11459}
11460```
11461#### Response example
11462```json
11463{
11464 "callback":"success",
11465 "contextWrites":{
11466 "#":{
11467 "to":"..."
11468 }
11469 }
11470}
11471```