Merge pull request #907 from stripe/remi/codegen-dcece9b

Add support for `out_of_band_amount` on `CreditNote` creation

src/main/java/com/stripe/model/CreditNote.java

@@ -214,11 +214,13 @@ public void setRefundObject(Refund expandableObject) {
    *       (using <code>refund</code>).
    *   <li>Customer balance credit: credit the customer’s balance (using <code>credit_amount</code>)
    *       which will be automatically applied to their next invoice when it’s finalized.
-   *   <li>Outside of Stripe credit: any positive value from the result of <code>
-   *       amount - refund_amount - credit_amount</code> is represented as an “outside of Stripe”
-   *       credit.
+   *   <li>Outside of Stripe credit: record the amount that is or will be credited outside of Stripe
+   *       (using <code>out_of_band_amount</code>).
    * </ul>
    *
+   * <p>For post-payment credit notes the sum of the refund, credit and outside of Stripe amounts
+   * must equal the credit note total.
+   *
    * <p>You may issue multiple credit notes for an invoice. Each credit note will increment the
    * invoice’s <code>pre_payment_credit_notes_amount</code> or <code>
    * post_payment_credit_notes_amount</code> depending on its <code>status</code> at the time of
@@ -239,11 +241,13 @@ public static CreditNote create(Map<String, Object> params) throws StripeExcepti
    *       (using <code>refund</code>).
    *   <li>Customer balance credit: credit the customer’s balance (using <code>credit_amount</code>)
    *       which will be automatically applied to their next invoice when it’s finalized.
-   *   <li>Outside of Stripe credit: any positive value from the result of <code>
-   *       amount - refund_amount - credit_amount</code> is represented as an “outside of Stripe”
-   *       credit.
+   *   <li>Outside of Stripe credit: record the amount that is or will be credited outside of Stripe
+   *       (using <code>out_of_band_amount</code>).
    * </ul>
    *
+   * <p>For post-payment credit notes the sum of the refund, credit and outside of Stripe amounts
+   * must equal the credit note total.
+   *
    * <p>You may issue multiple credit notes for an invoice. Each credit note will increment the
    * invoice’s <code>pre_payment_credit_notes_amount</code> or <code>
    * post_payment_credit_notes_amount</code> depending on its <code>status</code> at the time of
@@ -267,11 +271,13 @@ public static CreditNote create(Map<String, Object> params, RequestOptions optio
    *       (using <code>refund</code>).
    *   <li>Customer balance credit: credit the customer’s balance (using <code>credit_amount</code>)
    *       which will be automatically applied to their next invoice when it’s finalized.
-   *   <li>Outside of Stripe credit: any positive value from the result of <code>
-   *       amount - refund_amount - credit_amount</code> is represented as an “outside of Stripe”
-   *       credit.
+   *   <li>Outside of Stripe credit: record the amount that is or will be credited outside of Stripe
+   *       (using <code>out_of_band_amount</code>).
    * </ul>
    *
+   * <p>For post-payment credit notes the sum of the refund, credit and outside of Stripe amounts
+   * must equal the credit note total.
+   *
    * <p>You may issue multiple credit notes for an invoice. Each credit note will increment the
    * invoice’s <code>pre_payment_credit_notes_amount</code> or <code>
    * post_payment_credit_notes_amount</code> depending on its <code>status</code> at the time of
@@ -292,11 +298,13 @@ public static CreditNote create(CreditNoteCreateParams params) throws StripeExce
    *       (using <code>refund</code>).
    *   <li>Customer balance credit: credit the customer’s balance (using <code>credit_amount</code>)
    *       which will be automatically applied to their next invoice when it’s finalized.
-   *   <li>Outside of Stripe credit: any positive value from the result of <code>
-   *       amount - refund_amount - credit_amount</code> is represented as an “outside of Stripe”
-   *       credit.
+   *   <li>Outside of Stripe credit: record the amount that is or will be credited outside of Stripe
+   *       (using <code>out_of_band_amount</code>).
    * </ul>
    *
+   * <p>For post-payment credit notes the sum of the refund, credit and outside of Stripe amounts
+   * must equal the credit note total.
+   *
    * <p>You may issue multiple credit notes for an invoice. Each credit note will increment the
    * invoice’s <code>pre_payment_credit_notes_amount</code> or <code>
    * post_payment_credit_notes_amount</code> depending on its <code>status</code> at the time of

src/main/java/com/stripe/model/issuing/Transaction.java

@@ -22,6 +22,10 @@
 @EqualsAndHashCode(callSuper = false)
 public class Transaction extends ApiResource
     implements MetadataStore<Transaction>, BalanceTransactionSource {
+  /**
+   * The amount of this transaction in your currency. This is the amount that your balance will be
+   * updated by.
+   */
   @SerializedName("amount")
   Long amount;
 
@@ -76,9 +80,14 @@ public class Transaction extends ApiResource
   @SerializedName("livemode")
   Boolean livemode;
 
+  /**
+   * The amount that the merchant will receive, denominated in `merchant_currency`. It will be
+   * different from `amount` if the merchant is taking payment in a different currency.
+   */
   @SerializedName("merchant_amount")
   Long merchantAmount;
 
+  /** The currency with which the merchant is taking payment. */
   @SerializedName("merchant_currency")
   String merchantCurrency;
 

src/main/java/com/stripe/param/AccountLinkCreateParams.java

@@ -15,8 +15,8 @@ public class AccountLinkCreateParams extends ApiRequestParams {
   String account;
 
   /**
-   * The information the platform wants to collect from users up-front. Possible values are
-   * `currently_due` and `eventually_due`.
+   * Which information the platform needs to collect from the user. One of `currently_due` or
+   * `eventually_due`. Default is `currently_due`.
    */
   @SerializedName("collect")
   Collect collect;
@@ -107,8 +107,8 @@ public Builder setAccount(String account) {
     }
 
     /**
-     * The information the platform wants to collect from users up-front. Possible values are
-     * `currently_due` and `eventually_due`.
+     * Which information the platform needs to collect from the user. One of `currently_due` or
+     * `eventually_due`. Default is `currently_due`.
      */
     public Builder setCollect(Collect collect) {
       this.collect = collect;

src/main/java/com/stripe/param/CreditNoteCreateParams.java

@@ -50,6 +50,10 @@ public class CreditNoteCreateParams extends ApiRequestParams {
   @SerializedName("metadata")
   Map<String, String> metadata;
 
+  /** The integer amount in **%s** representing the amount that is credited outside of Stripe. */
+  @SerializedName("out_of_band_amount")
+  Long outOfBandAmount;
+
   /**
    * Reason for issuing this credit note, one of `duplicate`, `fraudulent`, `order_change`, or
    * `product_unsatisfactory`.
@@ -76,6 +80,7 @@ private CreditNoteCreateParams(
       String invoice,
       String memo,
       Map<String, String> metadata,
+      Long outOfBandAmount,
       Reason reason,
       String refund,
       Long refundAmount) {
@@ -86,6 +91,7 @@ private CreditNoteCreateParams(
     this.invoice = invoice;
     this.memo = memo;
     this.metadata = metadata;
+    this.outOfBandAmount = outOfBandAmount;
     this.reason = reason;
     this.refund = refund;
     this.refundAmount = refundAmount;
@@ -110,6 +116,8 @@ public static class Builder {
 
     private Map<String, String> metadata;
 
+    private Long outOfBandAmount;
+
     private Reason reason;
 
     private String refund;
@@ -126,6 +134,7 @@ public CreditNoteCreateParams build() {
           this.invoice,
           this.memo,
           this.metadata,
+          this.outOfBandAmount,
           this.reason,
           this.refund,
           this.refundAmount);
@@ -236,6 +245,12 @@ public Builder putAllMetadata(Map<String, String> map) {
       return this;
     }
 
+    /** The integer amount in **%s** representing the amount that is credited outside of Stripe. */
+    public Builder setOutOfBandAmount(Long outOfBandAmount) {
+      this.outOfBandAmount = outOfBandAmount;
+      return this;
+    }
+
     /**
      * Reason for issuing this credit note, one of `duplicate`, `fraudulent`, `order_change`, or
      * `product_unsatisfactory`.

src/main/java/com/stripe/param/CustomerCreateParams.java

@@ -604,7 +604,10 @@ public Builder setState(String state) {
 
   @Getter
   public static class InvoiceSettings {
-    /** Default custom fields to be displayed on invoices for this customer. */
+    /**
+     * Default custom fields to be displayed on invoices for this customer. When updating, pass an
+     * empty string to remove previously-defined fields.
+     */
     @SerializedName("custom_fields")
     Object customFields;
 
@@ -684,13 +687,19 @@ public Builder addAllCustomField(List<CustomField> elements) {
         return this;
       }
 
-      /** Default custom fields to be displayed on invoices for this customer. */
+      /**
+       * Default custom fields to be displayed on invoices for this customer. When updating, pass an
+       * empty string to remove previously-defined fields.
+       */
       public Builder setCustomFields(EmptyParam customFields) {
         this.customFields = customFields;
         return this;
       }
 
-      /** Default custom fields to be displayed on invoices for this customer. */
+      /**
+       * Default custom fields to be displayed on invoices for this customer. When updating, pass an
+       * empty string to remove previously-defined fields.
+       */
       public Builder setCustomFields(List<CustomField> customFields) {
         this.customFields = customFields;
         return this;

src/main/java/com/stripe/param/CustomerUpdateParams.java

@@ -709,7 +709,10 @@ public Builder setState(EmptyParam state) {
 
   @Getter
   public static class InvoiceSettings {
-    /** Default custom fields to be displayed on invoices for this customer. */
+    /**
+     * Default custom fields to be displayed on invoices for this customer. When updating, pass an
+     * empty string to remove previously-defined fields.
+     */
     @SerializedName("custom_fields")
     Object customFields;
 
@@ -789,13 +792,19 @@ public Builder addAllCustomField(List<CustomField> elements) {
         return this;
       }
 
-      /** Default custom fields to be displayed on invoices for this customer. */
+      /**
+       * Default custom fields to be displayed on invoices for this customer. When updating, pass an
+       * empty string to remove previously-defined fields.
+       */
       public Builder setCustomFields(EmptyParam customFields) {
         this.customFields = customFields;
         return this;
       }
 
-      /** Default custom fields to be displayed on invoices for this customer. */
+      /**
+       * Default custom fields to be displayed on invoices for this customer. When updating, pass an
+       * empty string to remove previously-defined fields.
+       */
       public Builder setCustomFields(List<CustomField> customFields) {
         this.customFields = customFields;
         return this;

src/main/java/com/stripe/param/InvoiceItemUpdateParams.java

@@ -64,7 +64,7 @@ public class InvoiceItemUpdateParams extends ApiRequestParams {
 
   /**
    * The tax rates which apply to the invoice item. When set, the `default_tax_rates` on the invoice
-   * do not apply to this invoice item.
+   * do not apply to this invoice item. Pass an empty string to remove previously-defined tax rates.
    */
   @SerializedName("tax_rates")
   Object taxRates;
@@ -309,7 +309,8 @@ public Builder addAllTaxRate(List<String> elements) {
 
     /**
      * The tax rates which apply to the invoice item. When set, the `default_tax_rates` on the
-     * invoice do not apply to this invoice item.
+     * invoice do not apply to this invoice item. Pass an empty string to remove previously-defined
+     * tax rates.
      */
     public Builder setTaxRates(EmptyParam taxRates) {
       this.taxRates = taxRates;
@@ -318,7 +319,8 @@ public Builder setTaxRates(EmptyParam taxRates) {
 
     /**
      * The tax rates which apply to the invoice item. When set, the `default_tax_rates` on the
-     * invoice do not apply to this invoice item.
+     * invoice do not apply to this invoice item. Pass an empty string to remove previously-defined
+     * tax rates.
      */
     public Builder setTaxRates(List<String> taxRates) {
       this.taxRates = taxRates;

src/main/java/com/stripe/param/InvoiceUpcomingParams.java

@@ -975,7 +975,7 @@ public Builder setStart(Long start) {
   public static class SubscriptionItem {
     /**
      * Define thresholds at which an invoice will be sent, and the subscription advanced to a new
-     * billing period.
+     * billing period. When updating, pass an empty string to remove previously-defined thresholds.
      */
     @SerializedName("billing_thresholds")
     Object billingThresholds;
@@ -1023,7 +1023,8 @@ public static class SubscriptionItem {
      * A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will
      * override the
      * [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates)
-     * on the Subscription.
+     * on the Subscription. When updating, pass an empty string to remove previously-defined tax
+     * rates.
      */
     @SerializedName("tax_rates")
     Object taxRates;
@@ -1088,7 +1089,8 @@ public SubscriptionItem build() {
 
       /**
        * Define thresholds at which an invoice will be sent, and the subscription advanced to a new
-       * billing period.
+       * billing period. When updating, pass an empty string to remove previously-defined
+       * thresholds.
        */
       public Builder setBillingThresholds(BillingThresholds billingThresholds) {
         this.billingThresholds = billingThresholds;
@@ -1097,7 +1099,8 @@ public Builder setBillingThresholds(BillingThresholds billingThresholds) {
 
       /**
        * Define thresholds at which an invoice will be sent, and the subscription advanced to a new
-       * billing period.
+       * billing period. When updating, pass an empty string to remove previously-defined
+       * thresholds.
        */
       public Builder setBillingThresholds(EmptyParam billingThresholds) {
         this.billingThresholds = billingThresholds;
@@ -1221,7 +1224,8 @@ public Builder addAllTaxRate(List<String> elements) {
        * A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will
        * override the
        * [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates)
-       * on the Subscription.
+       * on the Subscription. When updating, pass an empty string to remove previously-defined tax
+       * rates.
        */
       public Builder setTaxRates(EmptyParam taxRates) {
         this.taxRates = taxRates;
@@ -1232,7 +1236,8 @@ public Builder setTaxRates(EmptyParam taxRates) {
        * A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids. These Tax Rates will
        * override the
        * [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates)
-       * on the Subscription.
+       * on the Subscription. When updating, pass an empty string to remove previously-defined tax
+       * rates.
        */
       public Builder setTaxRates(List<String> taxRates) {
         this.taxRates = taxRates;

src/main/java/com/stripe/param/InvoiceUpdateParams.java

@@ -38,6 +38,7 @@ public class InvoiceUpdateParams extends ApiRequestParams {
   /**
    * A list of up to 4 custom fields to be displayed on the invoice. If a value for `custom_fields`
    * is specified, the list specified will replace the existing custom field list on this invoice.
+   * Pass an empty string to remove previously-defined fields.
    */
   @SerializedName("custom_fields")
   Object customFields;
@@ -67,7 +68,7 @@ public class InvoiceUpdateParams extends ApiRequestParams {
 
   /**
    * The tax rates that will apply to any line item that does not have `tax_rates` set. Pass an
-   * empty string to remove previously-set default tax rates.
+   * empty string to remove previously-defined tax rates.
    */
   @SerializedName("default_tax_rates")
   Object defaultTaxRates;
@@ -287,7 +288,7 @@ public Builder addAllCustomField(List<CustomField> elements) {
     /**
      * A list of up to 4 custom fields to be displayed on the invoice. If a value for
      * `custom_fields` is specified, the list specified will replace the existing custom field list
-     * on this invoice.
+     * on this invoice. Pass an empty string to remove previously-defined fields.
      */
     public Builder setCustomFields(EmptyParam customFields) {
       this.customFields = customFields;
@@ -297,7 +298,7 @@ public Builder setCustomFields(EmptyParam customFields) {
     /**
      * A list of up to 4 custom fields to be displayed on the invoice. If a value for
      * `custom_fields` is specified, the list specified will replace the existing custom field list
-     * on this invoice.
+     * on this invoice. Pass an empty string to remove previously-defined fields.
      */
     public Builder setCustomFields(List<CustomField> customFields) {
       this.customFields = customFields;
@@ -383,7 +384,7 @@ public Builder addAllDefaultTaxRate(List<String> elements) {
 
     /**
      * The tax rates that will apply to any line item that does not have `tax_rates` set. Pass an
-     * empty string to remove previously-set default tax rates.
+     * empty string to remove previously-defined tax rates.
      */
     public Builder setDefaultTaxRates(EmptyParam defaultTaxRates) {
       this.defaultTaxRates = defaultTaxRates;
@@ -392,7 +393,7 @@ public Builder setDefaultTaxRates(EmptyParam defaultTaxRates) {
 
     /**
      * The tax rates that will apply to any line item that does not have `tax_rates` set. Pass an
-     * empty string to remove previously-set default tax rates.
+     * empty string to remove previously-defined tax rates.
      */
     public Builder setDefaultTaxRates(List<String> defaultTaxRates) {
       this.defaultTaxRates = defaultTaxRates;