View Source Stripe.Order (Striped v0.4.0)

An Order describes a purchase being made by a customer, including the products & quantities being purchased, the order status, the payment information, and the billing/shipping details.

Related guide: Orders overview

Link to this section Summary

Types

If paying by acss_debit, this sub-hash contains details about the ACSS Debit payment method options to pass to the order's PaymentIntent.

The shipping address for the order.

If paying by afterpay_clearpay, this sub-hash contains details about the AfterpayClearpay payment method options to pass to the order's PaymentIntent.

If paying by alipay, this sub-hash contains details about the Alipay payment method options to pass to the order's PaymentIntent.

Settings for automatic tax calculation for this order.

If paying by bancontact, this sub-hash contains details about the Bancontact payment method options to pass to the order's PaymentIntent.

Configuration for the bank transfer funding type, if the funding_type is set to bank_transfer.

If paying by card, this sub-hash contains details about the Card payment method options to pass to the order's PaymentIntent.

If paying by customer_balance, this sub-hash contains details about the Customer Balance payment method options to pass to the order's PaymentIntent.

The estimated range for how long shipping will take, meant to be displayable to the customer. This will appear on CheckoutSessions.

Describes a fixed amount to charge for shipping. Must be present if type is fixed_amount.

If paying by ideal, this sub-hash contains details about the iDEAL payment method options to pass to the order's PaymentIntent.

If paying by klarna, this sub-hash contains details about the Klarna payment method options to pass to the order's PaymentIntent.

If paying by link, this sub-hash contains details about the Link payment method options to pass to the order's PaymentIntent.

Additional fields for Mandate creation

The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.

The lower bound of the estimated range. If empty, represents no lower bound.

If paying by oxxo, this sub-hash contains details about the OXXO payment method options to pass to the order's PaymentIntent.

If paying by p24, this sub-hash contains details about the P24 payment method options to pass to the order's PaymentIntent.

Payment information associated with the order, including payment settings.

PaymentMethod-specific configuration to provide to the order's PaymentIntent.

Data used to generate a new Price object inline.

Defines a Product inline and adds it to the Order.

If paying by sepa_debit, this sub-hash contains details about the SEPA Debit payment method options to pass to the order's PaymentIntent.

Settings describing how the order should configure generated PaymentIntents.

Parameters to create a new ad-hoc shipping rate for this order.

If paying by sofort, this sub-hash contains details about the Sofort payment method options to pass to the order's PaymentIntent.

t()

The order type.

Additional tax details about the purchaser to be used for this order.

Provides configuration for completing a transfer for the order after it is paid.

If paying by wechat_pay, this sub-hash contains details about the WeChat Pay payment method options to pass to the order's PaymentIntent.

Functions

Cancels the order as well as the payment intent if one is attached.

Creates a new open order object.

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

When retrieving an order, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Retrieves 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.

Submitting an Order transitions the status to processing and creates a PaymentIntent object so the order can be paid. If the Order has an amount_total of 0, no PaymentIntent object will be created. Once the order is submitted, its contents cannot be changed, unless the reopen method is called.

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

Link to this section Types

@type acss_debit() :: %{
  optional(:mandate_options) => mandate_options(),
  optional(:setup_future_usage) => :none | :off_session | :on_session,
  optional(:verification_method) => :automatic | :instant | :microdeposits
}

If paying by acss_debit, this sub-hash contains details about the ACSS Debit payment method options to pass to the order's PaymentIntent.

@type address() :: %{
  optional(:city) => binary(),
  optional(:country) => binary(),
  optional(:line1) => binary(),
  optional(:line2) => binary(),
  optional(:postal_code) => binary(),
  optional(:state) => binary()
}

The shipping address for the order.

@type afterpay_clearpay() :: %{
  optional(:capture_method) => :automatic | :manual,
  optional(:reference) => binary(),
  optional(:setup_future_usage) => :none
}

If paying by afterpay_clearpay, this sub-hash contains details about the AfterpayClearpay payment method options to pass to the order's PaymentIntent.

@type alipay() :: %{optional(:setup_future_usage) => :none | :off_session}

If paying by alipay, this sub-hash contains details about the Alipay payment method options to pass to the order's PaymentIntent.

@type automatic_tax() :: %{optional(:enabled) => boolean()}

Settings for automatic tax calculation for this order.

@type bancontact() :: %{
  optional(:preferred_language) => :de | :en | :fr | :nl,
  optional(:setup_future_usage) => :none | :off_session
}

If paying by bancontact, this sub-hash contains details about the Bancontact payment method options to pass to the order's PaymentIntent.

@type bank_transfer() :: %{
  optional(:eu_bank_transfer) => eu_bank_transfer(),
  optional(:requested_address_types) => [
    :iban | :sepa | :sort_code | :spei | :zengin
  ],
  optional(:type) =>
    :eu_bank_transfer
    | :gb_bank_transfer
    | :jp_bank_transfer
    | :mx_bank_transfer
}

Configuration for the bank transfer funding type, if the funding_type is set to bank_transfer.

@type billing_details() :: %{
  optional(:address) => address(),
  optional(:email) => binary(),
  optional(:name) => binary(),
  optional(:phone) => binary()
}
@type card() :: %{
  optional(:capture_method) => :automatic | :manual,
  optional(:setup_future_usage) => :none | :off_session | :on_session
}

If paying by card, this sub-hash contains details about the Card payment method options to pass to the order's PaymentIntent.

@type customer_balance() :: %{
  optional(:bank_transfer) => bank_transfer(),
  optional(:funding_type) => :bank_transfer,
  optional(:setup_future_usage) => :none
}

If paying by customer_balance, this sub-hash contains details about the Customer Balance payment method options to pass to the order's PaymentIntent.

@type delivery_estimate() :: %{
  optional(:maximum) => maximum(),
  optional(:minimum) => minimum()
}

The estimated range for how long shipping will take, meant to be displayable to the customer. This will appear on CheckoutSessions.

@type discounts() :: %{
  optional(:coupon) => binary(),
  optional(:discount) => binary(),
  optional(:promotion_code) => binary()
}
@type eu_bank_transfer() :: %{optional(:country) => binary()}
@type fixed_amount() :: %{
  optional(:amount) => integer(),
  optional(:currency) => binary(),
  optional(:currency_options) => map()
}

Describes a fixed amount to charge for shipping. Must be present if type is fixed_amount.

@type ideal() :: %{optional(:setup_future_usage) => :none | :off_session}

If paying by ideal, this sub-hash contains details about the iDEAL payment method options to pass to the order's PaymentIntent.

@type klarna() :: %{
  optional(:capture_method) => :manual,
  optional(:preferred_locale) =>
    :"da-DK"
    | :"de-AT"
    | :"de-CH"
    | :"de-DE"
    | :"en-AT"
    | :"en-AU"
    | :"en-BE"
    | :"en-CA"
    | :"en-CH"
    | :"en-DE"
    | :"en-DK"
    | :"en-ES"
    | :"en-FI"
    | :"en-FR"
    | :"en-GB"
    | :"en-IE"
    | :"en-IT"
    | :"en-NL"
    | :"en-NO"
    | :"en-NZ"
    | :"en-PL"
    | :"en-PT"
    | :"en-SE"
    | :"en-US"
    | :"es-ES"
    | :"es-US"
    | :"fi-FI"
    | :"fr-BE"
    | :"fr-CA"
    | :"fr-CH"
    | :"fr-FR"
    | :"it-CH"
    | :"it-IT"
    | :"nb-NO"
    | :"nl-BE"
    | :"nl-NL"
    | :"pl-PL"
    | :"pt-PT"
    | :"sv-FI"
    | :"sv-SE",
  optional(:setup_future_usage) => :none
}

If paying by klarna, this sub-hash contains details about the Klarna payment method options to pass to the order's PaymentIntent.

@type line_items() :: %{
  optional(:description) => binary(),
  optional(:discounts) => [discounts()] | binary(),
  optional(:price) => binary(),
  optional(:price_data) => price_data(),
  optional(:product) => binary(),
  optional(:product_data) => product_data(),
  optional(:quantity) => integer(),
  optional(:tax_rates) => [binary()] | binary()
}
@type link() :: %{
  optional(:capture_method) => :manual,
  optional(:persistent_token) => binary(),
  optional(:setup_future_usage) => :none | :off_session
}

If paying by link, this sub-hash contains details about the Link payment method options to pass to the order's PaymentIntent.

@type mandate_options() :: %{
  optional(:custom_mandate_url) => binary() | binary(),
  optional(:interval_description) => binary(),
  optional(:payment_schedule) => :combined | :interval | :sporadic,
  optional(:transaction_type) => :business | :personal
}

Additional fields for Mandate creation

@type maximum() :: %{
  optional(:unit) => :business_day | :day | :hour | :month | :week,
  optional(:value) => integer()
}

The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.

@type minimum() :: %{
  optional(:unit) => :business_day | :day | :hour | :month | :week,
  optional(:value) => integer()
}

The lower bound of the estimated range. If empty, represents no lower bound.

@type oxxo() :: %{
  optional(:expires_after_days) => integer(),
  optional(:setup_future_usage) => :none
}

If paying by oxxo, this sub-hash contains details about the OXXO payment method options to pass to the order's PaymentIntent.

@type p24() :: %{
  optional(:setup_future_usage) => :none,
  optional(:tos_shown_and_accepted) => boolean()
}

If paying by p24, this sub-hash contains details about the P24 payment method options to pass to the order's PaymentIntent.

@type package_dimensions() :: %{
  optional(:height) => number(),
  optional(:length) => number(),
  optional(:weight) => number(),
  optional(:width) => number()
}
@type payment() :: %{optional(:settings) => settings()}

Payment information associated with the order, including payment settings.

Link to this type

payment_method_options()

View Source
@type payment_method_options() :: %{
  optional(:acss_debit) => acss_debit(),
  optional(:afterpay_clearpay) => afterpay_clearpay(),
  optional(:alipay) => alipay(),
  optional(:bancontact) => bancontact(),
  optional(:card) => card(),
  optional(:customer_balance) => customer_balance(),
  optional(:ideal) => ideal(),
  optional(:klarna) => klarna(),
  optional(:link) => link(),
  optional(:oxxo) => oxxo(),
  optional(:p24) => p24(),
  optional(:sepa_debit) => sepa_debit(),
  optional(:sofort) => sofort(),
  optional(:wechat_pay) => wechat_pay()
}

PaymentMethod-specific configuration to provide to the order's PaymentIntent.

@type price_data() :: %{
  optional(:currency) => binary(),
  optional(:product) => binary(),
  optional(:tax_behavior) => :exclusive | :inclusive | :unspecified,
  optional(:unit_amount) => integer(),
  optional(:unit_amount_decimal) => binary()
}

Data used to generate a new Price object inline.

The price_data parameter is an alternative to using the product or price parameters. If you create products upfront and configure a Product.default_price, pass the product parameter when creating a line item. If you prefer not to define products upfront, or if you charge variable prices, pass the price_data parameter to describe the price for this line item.

Each time you pass price_data we create a Price for the product. This Price is hidden in both the Dashboard and API lists and cannot be reused.

@type product_data() :: %{
  optional(:description) => binary(),
  optional(:id) => binary(),
  optional(:images) => [binary()] | binary(),
  optional(:metadata) => %{optional(binary()) => binary()} | binary(),
  optional(:name) => binary(),
  optional(:package_dimensions) => package_dimensions() | binary(),
  optional(:shippable) => boolean(),
  optional(:tax_code) => binary(),
  optional(:url) => binary() | binary()
}

Defines a Product inline and adds it to the Order.

product_data is an alternative to the product parameter. If you created a Product upfront, use the product parameter to refer to the existing Product. But if you prefer not to create Products upfront, pass the product_data parameter to define a Product inline as part of configuring the Order.

product_data automatically creates a Product, just as if you had manually created the Product. If a Product with the same ID already exists, then product_data re-uses it to avoid duplicates.

@type sepa_debit() :: %{
  optional(:mandate_options) => map(),
  optional(:setup_future_usage) => :none | :off_session | :on_session
}

If paying by sepa_debit, this sub-hash contains details about the SEPA Debit payment method options to pass to the order's PaymentIntent.

@type settings() :: %{
  optional(:application_fee_amount) => integer(),
  optional(:payment_method_options) => payment_method_options(),
  optional(:payment_method_types) => [
    :acss_debit
    | :afterpay_clearpay
    | :alipay
    | :au_becs_debit
    | :bacs_debit
    | :bancontact
    | :card
    | :customer_balance
    | :eps
    | :fpx
    | :giropay
    | :grabpay
    | :ideal
    | :klarna
    | :link
    | :oxxo
    | :p24
    | :sepa_debit
    | :sofort
    | :wechat_pay
  ],
  optional(:return_url) => binary(),
  optional(:statement_descriptor) => binary(),
  optional(:statement_descriptor_suffix) => binary(),
  optional(:transfer_data) => transfer_data()
}

Settings describing how the order should configure generated PaymentIntents.

@type shipping_cost() :: %{
  optional(:shipping_rate) => binary(),
  optional(:shipping_rate_data) => shipping_rate_data()
}
@type shipping_details() :: %{
  optional(:address) => address(),
  optional(:name) => binary(),
  optional(:phone) => binary()
}
@type shipping_rate_data() :: %{
  optional(:delivery_estimate) => delivery_estimate(),
  optional(:display_name) => binary(),
  optional(:fixed_amount) => fixed_amount(),
  optional(:metadata) => %{optional(binary()) => binary()},
  optional(:tax_behavior) => :exclusive | :inclusive | :unspecified,
  optional(:tax_code) => binary(),
  optional(:type) => :fixed_amount
}

Parameters to create a new ad-hoc shipping rate for this order.

@type sofort() :: %{
  optional(:preferred_language) => :de | :en | :es | :fr | :it | :nl | :pl,
  optional(:setup_future_usage) => :none | :off_session
}

If paying by sofort, this sub-hash contains details about the Sofort payment method options to pass to the order's PaymentIntent.

@type t() :: %Stripe.Order{
  amount_subtotal: integer(),
  amount_total: integer(),
  application: (binary() | term()) | nil,
  automatic_tax: term(),
  billing_details: term() | nil,
  client_secret: binary() | nil,
  created: integer(),
  currency: binary(),
  customer: (binary() | Stripe.Customer.t() | Stripe.DeletedCustomer.t()) | nil,
  description: binary() | nil,
  discounts: term() | nil,
  id: binary(),
  ip_address: binary() | nil,
  line_items: term(),
  livemode: boolean(),
  metadata: term() | nil,
  object: binary(),
  payment: term(),
  shipping_cost: term() | nil,
  shipping_details: term() | nil,
  status: binary(),
  tax_details: term(),
  total_details: term()
}

The order type.

  • amount_subtotal Order cost before any discounts or taxes are applied. A positive integer representing the subtotal of the order in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
  • amount_total Total order cost after discounts and taxes are applied. A positive integer representing the cost of the order in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). To submit an order, the total must be either 0 or at least $0.50 USD or equivalent in charge currency.
  • application ID of the Connect application that created the Order, if any.
  • automatic_tax
  • billing_details Customer billing details associated with the order.
  • client_secret The client secret of this Order. Used for client-side retrieval using a publishable key.

The client secret can be used to complete a payment for an Order from your frontend. It should not be stored, logged, embedded in URLs, or exposed to anyone other than the customer. Make sure that you have TLS enabled on any page that includes the client secret.

Refer to our docs for creating and processing an order to learn about how client_secret should be handled.

  • 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 The customer which this orders belongs to.
  • description An arbitrary string attached to the object. Often useful for displaying to users.
  • discounts The discounts applied to the order. Use expand[]=discounts to expand each discount.
  • id Unique identifier for the object.
  • ip_address A recent IP address of the purchaser used for tax reporting and tax location inference.
  • line_items A list of line items the customer is ordering. Each line item includes information about the product, the quantity, and the resulting cost. There is a maximum of 100 line items.
  • livemode Has the value true if the object exists in live mode or the value false if the object exists in test mode.
  • 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.
  • object String representing the object's type. Objects of the same type share the same value.
  • payment
  • shipping_cost The details of the customer cost of shipping, including the customer chosen ShippingRate.
  • shipping_details Customer shipping information associated with the order.
  • status The overall status of the order.
  • tax_details
  • total_details
@type tax_details() :: %{
  optional(:tax_exempt) => :exempt | :none | :reverse,
  optional(:tax_ids) => [tax_ids()]
}

Additional tax details about the purchaser to be used for this order.

@type tax_ids() :: %{
  optional(:type) =>
    :ae_trn
    | :au_abn
    | :au_arn
    | :bg_uic
    | :br_cnpj
    | :br_cpf
    | :ca_bn
    | :ca_gst_hst
    | :ca_pst_bc
    | :ca_pst_mb
    | :ca_pst_sk
    | :ca_qst
    | :ch_vat
    | :cl_tin
    | :es_cif
    | :eu_oss_vat
    | :eu_vat
    | :gb_vat
    | :ge_vat
    | :hk_br
    | :hu_tin
    | :id_npwp
    | :il_vat
    | :in_gst
    | :is_vat
    | :jp_cn
    | :jp_rn
    | :kr_brn
    | :li_uid
    | :mx_rfc
    | :my_frp
    | :my_itn
    | :my_sst
    | :no_vat
    | :nz_gst
    | :ru_inn
    | :ru_kpp
    | :sa_vat
    | :sg_gst
    | :sg_uen
    | :si_tin
    | :th_vat
    | :tw_vat
    | :ua_vat
    | :us_ein
    | :za_vat,
  optional(:value) => binary()
}
@type transfer_data() :: %{
  optional(:amount) => integer(),
  optional(:destination) => binary()
}

Provides configuration for completing a transfer for the order after it is paid.

@type wechat_pay() :: %{
  optional(:app_id) => binary(),
  optional(:client) => :android | :ios | :web,
  optional(:setup_future_usage) => :none
}

If paying by wechat_pay, this sub-hash contains details about the WeChat Pay payment method options to pass to the order's PaymentIntent.

Link to this section Functions

Link to this function

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

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

Cancels the order as well as the payment intent if one is attached.

Details

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

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

View Source
@spec create(
  client :: Stripe.t(),
  params :: %{
    optional(:automatic_tax) => automatic_tax(),
    optional(:billing_details) => billing_details() | binary(),
    optional(:currency) => binary(),
    optional(:customer) => binary(),
    optional(:description) => binary(),
    optional(:discounts) => [discounts()] | binary(),
    optional(:expand) => [binary()],
    optional(:ip_address) => binary(),
    optional(:line_items) => [line_items()],
    optional(:metadata) => %{optional(binary()) => binary()},
    optional(:payment) => payment(),
    optional(:shipping_cost) => shipping_cost() | binary(),
    optional(:shipping_details) => shipping_details() | binary(),
    optional(:tax_details) => tax_details()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Creates a new open order object.

Details

  • Method: post
  • Path: /v1/orders
Link to this function

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

View Source
@spec list(
  client :: Stripe.t(),
  params :: %{
    optional(:customer) => binary(),
    optional(:ending_before) => binary(),
    optional(:expand) => [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 your orders. The orders are returned sorted by creation date, with the most recently created orders appearing first.

Details

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

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

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

When retrieving an order, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Details

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

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

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

Reopens a submitted order.

Details

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

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

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

Retrieves 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.

Details

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

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

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

Submitting an Order transitions the status to processing and creates a PaymentIntent object so the order can be paid. If the Order has an amount_total of 0, no PaymentIntent object will be created. Once the order is submitted, its contents cannot be changed, unless the reopen method is called.

Details

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

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

View Source
@spec update(
  client :: Stripe.t(),
  id :: binary(),
  params :: %{
    optional(:automatic_tax) => automatic_tax(),
    optional(:billing_details) => billing_details() | binary(),
    optional(:currency) => binary(),
    optional(:customer) => binary(),
    optional(:description) => binary(),
    optional(:discounts) => [discounts()] | binary(),
    optional(:expand) => [binary()],
    optional(:ip_address) => binary(),
    optional(:line_items) => [line_items()],
    optional(:metadata) => %{optional(binary()) => binary()} | binary(),
    optional(:payment) => payment(),
    optional(:shipping_cost) => shipping_cost() | binary(),
    optional(:shipping_details) => shipping_details() | binary(),
    optional(:tax_details) => tax_details()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

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

Details

  • Method: post
  • Path: /v1/orders/{id}