View Source Stripe.CreditNote (stripity_stripe v3.3.1)

Issue a credit note to adjust an invoice's amount after the invoice is finalized.

Related guide: Credit notes

Summary

Types

The PaymentRecord refund details to link to this credit note. Required when type is payment_record_refund.

t()

The credit_note type.

Functions

Issue a credit note to adjust the amount of a finalized invoice. A credit note will first reduce the invoice’s amount_remaining (and amount_due), but not below zero.This amount is indicated by the credit note’s pre_payment_amount. The excess amount is indicated by post_payment_amount, and it can result in any combination of the following

Returns a list of credit notes.

Get a preview of a credit note without creating it.

When retrieving a credit note preview, you’ll get a lines property containing the first handful of those items. This URL you can retrieve the full (paginated) list of line items.

Retrieves the credit note object with the given identifier.

Updates an existing credit note.

Marks a credit note as void. Learn more about voiding credit notes.

Types

@type created() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}
@type lines() :: %{
  optional(:amount) => integer(),
  optional(:description) => binary(),
  optional(:invoice_line_item) => binary(),
  optional(:quantity) => integer(),
  optional(:tax_amounts) => [tax_amounts()] | binary(),
  optional(:tax_rates) => [binary()] | binary(),
  optional(:type) => :custom_line_item | :invoice_line_item,
  optional(:unit_amount) => integer(),
  optional(:unit_amount_decimal) => binary()
}
Link to this type

payment_record_refund()

View Source
@type payment_record_refund() :: %{
  optional(:payment_record) => binary(),
  optional(:refund_group) => binary()
}

The PaymentRecord refund details to link to this credit note. Required when type is payment_record_refund.

@type refunds() :: %{
  optional(:amount_refunded) => integer(),
  optional(:payment_record_refund) => payment_record_refund(),
  optional(:refund) => binary(),
  optional(:type) => :payment_record_refund | :refund
}
@type shipping_cost() :: %{optional(:shipping_rate) => binary()}
@type t() :: %Stripe.CreditNote{
  amount: integer(),
  amount_shipping: integer(),
  created: integer(),
  currency: binary(),
  customer: binary() | Stripe.Customer.t() | Stripe.DeletedCustomer.t(),
  customer_balance_transaction:
    (binary() | Stripe.CustomerBalanceTransaction.t()) | nil,
  discount_amount: integer(),
  discount_amounts: term(),
  effective_at: integer() | nil,
  id: binary(),
  invoice: binary() | Stripe.Invoice.t(),
  lines: term(),
  livemode: boolean(),
  memo: binary() | nil,
  metadata: term() | nil,
  number: binary(),
  object: binary(),
  out_of_band_amount: integer() | nil,
  pdf: binary(),
  post_payment_amount: integer(),
  pre_payment_amount: integer(),
  pretax_credit_amounts: term(),
  reason: binary() | nil,
  refunds: term(),
  shipping_cost: term() | nil,
  status: binary(),
  subtotal: integer(),
  subtotal_excluding_tax: integer() | nil,
  total: integer(),
  total_excluding_tax: integer() | nil,
  total_taxes: term() | nil,
  type: binary(),
  voided_at: integer() | nil
}

The credit_note type.

  • amount The integer amount in cents (or local equivalent) representing the total amount of the credit note, including tax.
  • amount_shipping This is the sum of all the shipping amounts.
  • created Time at which the object was created. Measured in seconds since the Unix epoch.
  • currency Three-letter ISO currency code, in lowercase. Must be a supported currency.
  • customer ID of the customer.
  • customer_balance_transaction Customer balance transaction related to this credit note.
  • discount_amount The integer amount in cents (or local equivalent) representing the total amount of discount that was credited.
  • discount_amounts The aggregate amounts calculated per discount for all line items.
  • effective_at The date when this credit note is in effect. Same as created unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the credit note PDF.
  • id Unique identifier for the object.
  • invoice ID of the invoice.
  • lines Line items that make up the credit note
  • livemode Has the value true if the object exists in live mode or the value false if the object exists in test mode.
  • memo Customer-facing text that appears on the credit note PDF.
  • metadata Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
  • number A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
  • object String representing the object's type. Objects of the same type share the same value.
  • out_of_band_amount Amount that was credited outside of Stripe.
  • pdf The link to download the PDF of the credit note.
  • post_payment_amount The amount of the credit note that was refunded to the customer, credited to the customer's balance, credited outside of Stripe, or any combination thereof.
  • pre_payment_amount The amount of the credit note by which the invoice's amount_remaining and amount_due were reduced.
  • pretax_credit_amounts The pretax credit amounts (ex: discount, credit grants, etc) for all line items.
  • reason Reason for issuing this credit note, one of duplicate, fraudulent, order_change, or product_unsatisfactory
  • refunds Refunds related to this credit note.
  • shipping_cost The details of the cost of shipping, including the ShippingRate applied to the invoice.
  • status Status of this credit note, one of issued or void. Learn more about voiding credit notes.
  • subtotal The integer amount in cents (or local equivalent) representing the amount of the credit note, excluding exclusive tax and invoice level discounts.
  • subtotal_excluding_tax The integer amount in cents (or local equivalent) representing the amount of the credit note, excluding all tax and invoice level discounts.
  • total The integer amount in cents (or local equivalent) representing the total amount of the credit note, including tax and all discount.
  • total_excluding_tax The integer amount in cents (or local equivalent) representing the total amount of the credit note, excluding tax, but including discounts.
  • total_taxes The aggregate tax information for all line items.
  • type Type of this credit note, one of pre_payment or post_payment. A pre_payment credit note means it was issued when the invoice was open. A post_payment credit note means it was issued when the invoice was paid.
  • voided_at The time that the credit note was voided.
@type tax_amounts() :: %{
  optional(:amount) => integer(),
  optional(:tax_rate) => binary(),
  optional(:taxable_amount) => integer()
}

Functions

Link to this function

create(params \\ %{}, opts \\ [])

View Source
@spec create(
  params :: %{
    optional(:amount) => integer(),
    optional(:credit_amount) => integer(),
    optional(:effective_at) => integer(),
    optional(:email_type) => :credit_note | :none,
    optional(:expand) => [binary()],
    optional(:invoice) => binary(),
    optional(:lines) => [lines()],
    optional(:memo) => binary(),
    optional(:metadata) => %{optional(binary()) => binary()},
    optional(:out_of_band_amount) => integer(),
    optional(:reason) =>
      :duplicate | :fraudulent | :order_change | :product_unsatisfactory,
    optional(:refund_amount) => integer(),
    optional(:refunds) => [refunds()],
    optional(:shipping_cost) => shipping_cost()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Issue a credit note to adjust the amount of a finalized invoice. A credit note will first reduce the invoice’s amount_remaining (and amount_due), but not below zero.This amount is indicated by the credit note’s pre_payment_amount. The excess amount is indicated by post_payment_amount, and it can result in any combination of the following:

  • Refunds: create a new refund (using refund_amount) or link existing refunds (using refunds).
  • Customer balance credit: credit the customer’s balance (using credit_amount) which will be automatically applied to their next invoice when it’s finalized.
  • Outside of Stripe credit: record the amount that is or will be credited outside of Stripe (using out_of_band_amount).

The sum of refunds, customer balance credits, and outside of Stripe credits must equal the post_payment_amount.

You may issue multiple credit notes for an invoice. Each credit note may increment the invoice’s pre_payment_credit_notes_amount,post_payment_credit_notes_amount, or both, depending on the invoice’s amount_remaining at the time of credit note creation.

#### Details * Method: `post` * Path: `/v1/credit_notes`

Link to this function

list(params \\ %{}, opts \\ [])

View Source
@spec list(
  params :: %{
    optional(:created) => created() | integer(),
    optional(:customer) => binary(),
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:invoice) => binary(),
    optional(:limit) => integer(),
    optional(:starting_after) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(t())} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Returns a list of credit notes.

Details

  • Method: get
  • Path: /v1/credit_notes
Link to this function

preview(params \\ %{}, opts \\ [])

View Source
@spec preview(
  params :: %{
    optional(:amount) => integer(),
    optional(:credit_amount) => integer(),
    optional(:effective_at) => integer(),
    optional(:email_type) => :credit_note | :none,
    optional(:expand) => [binary()],
    optional(:invoice) => binary(),
    optional(:lines) => [lines()],
    optional(:memo) => binary(),
    optional(:metadata) => %{optional(binary()) => binary()},
    optional(:out_of_band_amount) => integer(),
    optional(:reason) =>
      :duplicate | :fraudulent | :order_change | :product_unsatisfactory,
    optional(:refund_amount) => integer(),
    optional(:refunds) => [refunds()],
    optional(:shipping_cost) => shipping_cost()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Get a preview of a credit note without creating it.

Details

  • Method: get
  • Path: /v1/credit_notes/preview
Link to this function

preview_lines(params \\ %{}, opts \\ [])

View Source
@spec preview_lines(
  params :: %{
    optional(:amount) => integer(),
    optional(:credit_amount) => integer(),
    optional(:effective_at) => integer(),
    optional(:email_type) => :credit_note | :none,
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:invoice) => binary(),
    optional(:limit) => integer(),
    optional(:lines) => [lines()],
    optional(:memo) => binary(),
    optional(:metadata) => %{optional(binary()) => binary()},
    optional(:out_of_band_amount) => integer(),
    optional(:reason) =>
      :duplicate | :fraudulent | :order_change | :product_unsatisfactory,
    optional(:refund_amount) => integer(),
    optional(:refunds) => [refunds()],
    optional(:shipping_cost) => shipping_cost(),
    optional(:starting_after) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(Stripe.CreditNoteLineItem.t())}
  | {:error, Stripe.ApiErrors.t()}
  | {:error, term()}

When retrieving a credit note preview, you’ll get a lines property containing the first handful of those items. This URL you can retrieve the full (paginated) list of line items.

Details

  • Method: get
  • Path: /v1/credit_notes/preview/lines
Link to this function

retrieve(id, params \\ %{}, opts \\ [])

View Source
@spec retrieve(
  id :: binary(),
  params :: %{optional(:expand) => [binary()]},
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Retrieves the credit note object with the given identifier.

Details

  • Method: get
  • Path: /v1/credit_notes/{id}
Link to this function

update(id, params \\ %{}, opts \\ [])

View Source
@spec update(
  id :: binary(),
  params :: %{
    optional(:expand) => [binary()],
    optional(:memo) => binary(),
    optional(:metadata) => %{optional(binary()) => binary()}
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Updates an existing credit note.

Details

  • Method: post
  • Path: /v1/credit_notes/{id}
Link to this function

void_credit_note(id, params \\ %{}, opts \\ [])

View Source
@spec void_credit_note(
  id :: binary(),
  params :: %{optional(:expand) => [binary()]},
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Marks a credit note as void. Learn more about voiding credit notes.

Details

  • Method: post
  • Path: /v1/credit_notes/{id}/void