diff --git a/OPENAPI_VERSION b/OPENAPI_VERSION index 1129f2eb6..dbdf3c1cb 100644 --- a/OPENAPI_VERSION +++ b/OPENAPI_VERSION @@ -1 +1 @@ -v1103 \ No newline at end of file +v1116 \ No newline at end of file diff --git a/stripe/_customer.py b/stripe/_customer.py index 28d8ff286..012fcbad8 100644 --- a/stripe/_customer.py +++ b/stripe/_customer.py @@ -1395,7 +1395,7 @@ class SearchParams(RequestOptions): """ next_invoice_sequence: Optional[int] """ - The suffix of the customer's next invoice number (for example, 0001). + The suffix of the customer's next invoice number (for example, 0001). When the account uses account level sequencing, this parameter is ignored in API requests and the field omitted in API responses. """ object: Literal["customer"] """ diff --git a/stripe/_customer_session.py b/stripe/_customer_session.py index 296199474..f7c8a41ce 100644 --- a/stripe/_customer_session.py +++ b/stripe/_customer_session.py @@ -19,8 +19,8 @@ class CustomerSession(CreateableAPIResource["CustomerSession"]): """ - A customer session allows you to grant client access to Stripe's frontend SDKs (like StripeJs) - control over a customer. + A Customer Session allows you to grant Stripe's frontend SDKs (like Stripe.js) client-side access + control over a Customer. """ OBJECT_NAME: ClassVar[Literal["customer_session"]] = "customer_session" @@ -58,7 +58,7 @@ class CreateParams(RequestOptions): """ customer: str """ - The ID of an existing customer for which to create the customer session. + The ID of an existing customer for which to create the Customer Session. """ expand: NotRequired[List[str]] """ @@ -93,13 +93,13 @@ class CreateParamsComponentsPricingTable(TypedDict): client_secret: str """ - The client secret of this customer session. Used on the client to set up secure access to the given `customer`. + The client secret of this Customer Session. Used on the client to set up secure access to the given `customer`. The client secret can be used to provide access to `customer` from your frontend. It should not be stored, logged, or exposed to anyone other than the relevant customer. Make sure that you have TLS enabled on any page that includes the client secret. """ components: Optional[Components] """ - Configuration for the components supported by this customer session. + Configuration for the components supported by this Customer Session. """ created: int """ @@ -107,11 +107,11 @@ class CreateParamsComponentsPricingTable(TypedDict): """ customer: ExpandableField["Customer"] """ - The customer the customer session was created for. + The Customer the Customer Session was created for. """ expires_at: int """ - The timestamp at which this customer session will expire. + The timestamp at which this Customer Session will expire. """ livemode: bool """ @@ -127,7 +127,7 @@ def create( cls, **params: Unpack["CustomerSession.CreateParams"] ) -> "CustomerSession": """ - Creates a customer session object that includes a single-use client secret that you can use on your front-end to grant client-side API access for certain customer resources. + Creates a Customer Session object that includes a single-use client secret that you can use on your front-end to grant client-side API access for certain customer resources. """ return cast( "CustomerSession", @@ -143,7 +143,7 @@ async def create_async( cls, **params: Unpack["CustomerSession.CreateParams"] ) -> "CustomerSession": """ - Creates a customer session object that includes a single-use client secret that you can use on your front-end to grant client-side API access for certain customer resources. + Creates a Customer Session object that includes a single-use client secret that you can use on your front-end to grant client-side API access for certain customer resources. """ return cast( "CustomerSession", diff --git a/stripe/_customer_session_service.py b/stripe/_customer_session_service.py index 737e6f775..1bcb652fc 100644 --- a/stripe/_customer_session_service.py +++ b/stripe/_customer_session_service.py @@ -15,7 +15,7 @@ class CreateParams(TypedDict): """ customer: str """ - The ID of an existing customer for which to create the customer session. + The ID of an existing customer for which to create the Customer Session. """ expand: NotRequired[List[str]] """ @@ -54,7 +54,7 @@ def create( options: RequestOptions = {}, ) -> CustomerSession: """ - Creates a customer session object that includes a single-use client secret that you can use on your front-end to grant client-side API access for certain customer resources. + Creates a Customer Session object that includes a single-use client secret that you can use on your front-end to grant client-side API access for certain customer resources. """ return cast( CustomerSession, @@ -74,7 +74,7 @@ async def create_async( options: RequestOptions = {}, ) -> CustomerSession: """ - Creates a customer session object that includes a single-use client secret that you can use on your front-end to grant client-side API access for certain customer resources. + Creates a Customer Session object that includes a single-use client secret that you can use on your front-end to grant client-side API access for certain customer resources. """ return cast( CustomerSession, diff --git a/stripe/_invoice.py b/stripe/_invoice.py index 0f7a80139..719273d7b 100644 --- a/stripe/_invoice.py +++ b/stripe/_invoice.py @@ -418,6 +418,7 @@ class LastFinalizationError(StripeObject): "parameters_exclusive", "payment_intent_action_required", "payment_intent_authentication_failure", + "payment_intent_fx_quote_invalid", "payment_intent_incompatible_payment_method", "payment_intent_invalid_parameter", "payment_intent_konbini_rejected_confirmation_number", @@ -1006,6 +1007,215 @@ class TransferData(StripeObject): The account where funds from the payment will be transferred to upon payment success. """ + class AddLinesParams(RequestOptions): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + invoice_metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + lines: List["Invoice.AddLinesParamsLine"] + """ + The line items to add. + """ + + class AddLinesParamsLine(TypedDict): + amount: NotRequired[int] + """ + The integer amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. If you want to apply a credit to the customer's account, pass a negative amount. + """ + description: NotRequired[str] + """ + An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. + """ + discountable: NotRequired[bool] + """ + Controls whether discounts apply to this line item. Defaults to false for prorations or negative line items, and true for all other line items. Cannot be set to true for prorations. + """ + discounts: NotRequired[ + "Literal['']|List[Invoice.AddLinesParamsLineDiscount]" + ] + """ + The coupons, promotion codes & existing discounts which apply to the line item. Item discounts are applied before invoice discounts. Pass an empty string to remove previously-defined discounts. + """ + invoice_item: NotRequired[str] + """ + ID of an unassigned invoice item to assign to this invoice. If not provided, a new item will be created. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + period: NotRequired["Invoice.AddLinesParamsLinePeriod"] + """ + The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. + """ + price: NotRequired[str] + """ + The ID of the price object. One of `price` or `price_data` is required. + """ + price_data: NotRequired["Invoice.AddLinesParamsLinePriceData"] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. One of `price` or `price_data` is required. + """ + quantity: NotRequired[int] + """ + Non-negative integer. The quantity of units for the line item. + """ + tax_amounts: NotRequired[ + "Literal['']|List[Invoice.AddLinesParamsLineTaxAmount]" + ] + """ + A list of up to 10 tax amounts for this line item. This can be useful if you calculate taxes on your own or use a third-party to calculate them. You cannot set tax amounts if any line item has [tax_rates](https://stripe.com/docs/api/invoices/line_item#invoice_line_item_object-tax_rates) or if the invoice has [default_tax_rates](https://stripe.com/docs/api/invoices/object#invoice_object-default_tax_rates) or uses [automatic tax](https://stripe.com/docs/tax/invoicing). Pass an empty string to remove previously defined tax amounts. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates which apply to the line item. When set, the `default_tax_rates` on the invoice do not apply to this line item. Pass an empty string to remove previously-defined tax rates. + """ + + class AddLinesParamsLineDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class AddLinesParamsLinePeriod(TypedDict): + end: int + """ + The end of the period, which must be greater than or equal to the start. This value is inclusive. + """ + start: int + """ + The start of the period. This value is inclusive. + """ + + class AddLinesParamsLinePriceData(TypedDict): + currency: str + """ + Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). + """ + product: NotRequired[str] + """ + The ID of the product that this price will belong to. One of `product` or `product_data` is required. + """ + product_data: NotRequired[ + "Invoice.AddLinesParamsLinePriceDataProductData" + ] + """ + Data used to generate a new product object inline. One of `product` or `product_data` is required. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A non-negative integer in cents (or local equivalent) representing how much to charge. One of `unit_amount` or `unit_amount_decimal` is required. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class AddLinesParamsLinePriceDataProductData(TypedDict): + description: NotRequired[str] + """ + The product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes. + """ + images: NotRequired[List[str]] + """ + A list of up to 8 URLs of images for this product, meant to be displayable to the customer. + """ + metadata: NotRequired[Dict[str, str]] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + name: str + """ + The product's name, meant to be displayable to the customer. + """ + tax_code: NotRequired[str] + """ + A [tax code](https://stripe.com/docs/tax/tax-categories) ID. + """ + + class AddLinesParamsLineTaxAmount(TypedDict): + amount: int + """ + The amount, in cents (or local equivalent), of the tax. + """ + tax_rate_data: "Invoice.AddLinesParamsLineTaxAmountTaxRateData" + """ + Data to find or create a TaxRate object. + + Stripe automatically creates or reuses a TaxRate object for each tax amount. If the `tax_rate_data` exactly matches a previous value, Stripe will reuse the TaxRate object. TaxRate objects created automatically by Stripe are immediately archived, do not appear in the line item's `tax_rates`, and cannot be directly added to invoices, payments, or line items. + """ + taxable_amount: int + """ + The amount on which tax is calculated, in cents (or local equivalent). + """ + + class AddLinesParamsLineTaxAmountTaxRateData(TypedDict): + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + description: NotRequired[str] + """ + An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers. + """ + display_name: str + """ + The display name of the tax rate, which will be shown to users. + """ + inclusive: bool + """ + This specifies if the tax rate is inclusive or exclusive. + """ + jurisdiction: NotRequired[str] + """ + The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer's invoice. + """ + percentage: float + """ + The statutory tax rate percent. This field accepts decimal values between 0 and 100 inclusive with at most 4 decimal places. To accommodate fixed-amount taxes, set the percentage to zero. Stripe will not display zero percentages on the invoice unless the `amount` of the tax is also zero. + """ + state: NotRequired[str] + """ + [ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2:US), without country prefix. For example, "NY" for New York, United States. + """ + tax_type: NotRequired[ + Literal[ + "amusement_tax", + "communications_tax", + "gst", + "hst", + "igst", + "jct", + "lease_tax", + "pst", + "qst", + "rst", + "sales_tax", + "vat", + ] + ] + """ + The high-level tax type, such as `vat` or `sales_tax`. + """ + class CreateParams(RequestOptions): account_tax_ids: NotRequired["Literal['']|List[str]"] """ @@ -3342,6 +3552,30 @@ class PayParams(RequestOptions): A payment source to be charged. The source must be the ID of a source belonging to the customer associated with the invoice being paid. """ + class RemoveLinesParams(RequestOptions): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + invoice_metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + lines: List["Invoice.RemoveLinesParamsLine"] + """ + The line items to remove. + """ + + class RemoveLinesParamsLine(TypedDict): + behavior: Literal["delete", "unassign"] + """ + Either `delete` or `unassign`. Deleted line items are permanently deleted. Unassigned line items can be reassigned to an invoice. + """ + id: str + """ + ID of an existing line item to remove from this invoice. + """ + class RetrieveParams(RequestOptions): expand: NotRequired[List[str]] """ @@ -5640,89 +5874,298 @@ class UpcomingParamsSubscriptionItemPriceDataRecurring(TypedDict): The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). """ - class VoidInvoiceParams(RequestOptions): + class UpdateLinesParams(RequestOptions): expand: NotRequired[List[str]] """ Specifies which fields in the response should be expanded. """ + invoice_metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. For [type=subscription](https://stripe.com/docs/api/invoices/line_item#invoice_line_item_object-type) line items, the incoming metadata specified on the request is directly used to set this value, in contrast to [type=invoiceitem](api/invoices/line_item#invoice_line_item_object-type) line items, where any existing metadata on the invoice line is merged with the incoming data. + """ + lines: List["Invoice.UpdateLinesParamsLine"] + """ + The line items to update. + """ - account_country: Optional[str] - """ - The country of the business associated with this invoice, most often the business creating the invoice. - """ - account_name: Optional[str] - """ - The public name of the business associated with this invoice, most often the business creating the invoice. - """ - account_tax_ids: Optional[List[ExpandableField["TaxId"]]] - """ - The account tax IDs associated with the invoice. Only editable when the invoice is a draft. - """ - amount_due: int - """ - Final amount due at this time for this invoice. If the invoice's total is smaller than the minimum charge amount, for example, or if there is account credit that can be applied to the invoice, the `amount_due` may be 0. If there is a positive `starting_balance` for the invoice (the customer owes money), the `amount_due` will also take that into account. The charge that gets generated for the invoice will be for the amount specified in `amount_due`. - """ - amount_paid: int - """ - The amount, in cents (or local equivalent), that was paid. - """ - amount_remaining: int - """ - The difference between amount_due and amount_paid, in cents (or local equivalent). - """ - amount_shipping: int - """ - This is the sum of all the shipping amounts. - """ - application: Optional[ExpandableField["Application"]] - """ - ID of the Connect Application that created the invoice. - """ - application_fee_amount: Optional[int] - """ - The fee in cents (or local equivalent) that will be applied to the invoice and transferred to the application owner's Stripe account when the invoice is paid. - """ - attempt_count: int - """ - Number of payment attempts made for this invoice, from the perspective of the payment retry schedule. Any payment attempt counts as the first attempt, and subsequently only automatic retries increment the attempt count. In other words, manual payment attempts after the first attempt do not affect the retry schedule. If a failure is returned with a non-retryable return code, the invoice can no longer be retried unless a new payment method is obtained. Retries will continue to be scheduled, and attempt_count will continue to increment, but retries will only be executed if a new payment method is obtained. - """ - attempted: bool - """ - Whether an attempt has been made to pay the invoice. An invoice is not attempted until 1 hour after the `invoice.created` webhook, for example, so you might not want to display that invoice as unpaid to your users. - """ - auto_advance: Optional[bool] - """ - Controls whether Stripe performs [automatic collection](https://stripe.com/docs/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action. - """ - automatic_tax: AutomaticTax - billing_reason: Optional[ - Literal[ - "automatic_pending_invoice_item_invoice", - "manual", - "quote_accept", - "subscription", - "subscription_create", - "subscription_cycle", - "subscription_threshold", - "subscription_update", - "upcoming", + class UpdateLinesParamsLine(TypedDict): + amount: NotRequired[int] + """ + The integer amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. If you want to apply a credit to the customer's account, pass a negative amount. + """ + description: NotRequired[str] + """ + An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. + """ + discountable: NotRequired[bool] + """ + Controls whether discounts apply to this line item. Defaults to false for prorations or negative line items, and true for all other line items. Cannot be set to true for prorations. + """ + discounts: NotRequired[ + "Literal['']|List[Invoice.UpdateLinesParamsLineDiscount]" ] - ] - """ - Indicates the reason why the invoice was created. - - * `manual`: Unrelated to a subscription, for example, created via the invoice editor. - * `subscription`: No longer in use. Applies to subscriptions from before May 2018 where no distinction was made between updates, cycles, and thresholds. - * `subscription_create`: A new subscription was created. - * `subscription_cycle`: A subscription advanced into a new period. - * `subscription_threshold`: A subscription reached a billing threshold. - * `subscription_update`: A subscription was updated. - * `upcoming`: Reserved for simulated invoices, per the upcoming invoice endpoint. - """ - charge: Optional[ExpandableField["Charge"]] - """ - ID of the latest charge generated for this invoice, if any. - """ + """ + The coupons, promotion codes & existing discounts which apply to the line item. Item discounts are applied before invoice discounts. Pass an empty string to remove previously-defined discounts. + """ + id: str + """ + ID of an existing line item on the invoice. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. For [type=subscription](https://stripe.com/docs/api/invoices/line_item#invoice_line_item_object-type) line items, the incoming metadata specified on the request is directly used to set this value, in contrast to [type=invoiceitem](api/invoices/line_item#invoice_line_item_object-type) line items, where any existing metadata on the invoice line is merged with the incoming data. + """ + period: NotRequired["Invoice.UpdateLinesParamsLinePeriod"] + """ + The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. + """ + price: NotRequired[str] + """ + The ID of the price object. One of `price` or `price_data` is required. + """ + price_data: NotRequired["Invoice.UpdateLinesParamsLinePriceData"] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. One of `price` or `price_data` is required. + """ + quantity: NotRequired[int] + """ + Non-negative integer. The quantity of units for the line item. + """ + tax_amounts: NotRequired[ + "Literal['']|List[Invoice.UpdateLinesParamsLineTaxAmount]" + ] + """ + A list of up to 10 tax amounts for this line item. This can be useful if you calculate taxes on your own or use a third-party to calculate them. You cannot set tax amounts if any line item has [tax_rates](https://stripe.com/docs/api/invoices/line_item#invoice_line_item_object-tax_rates) or if the invoice has [default_tax_rates](https://stripe.com/docs/api/invoices/object#invoice_object-default_tax_rates) or uses [automatic tax](https://stripe.com/docs/tax/invoicing). Pass an empty string to remove previously defined tax amounts. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates which apply to the line item. When set, the `default_tax_rates` on the invoice do not apply to this line item. Pass an empty string to remove previously-defined tax rates. + """ + + class UpdateLinesParamsLineDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class UpdateLinesParamsLinePeriod(TypedDict): + end: int + """ + The end of the period, which must be greater than or equal to the start. This value is inclusive. + """ + start: int + """ + The start of the period. This value is inclusive. + """ + + class UpdateLinesParamsLinePriceData(TypedDict): + currency: str + """ + Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). + """ + product: NotRequired[str] + """ + The ID of the product that this price will belong to. One of `product` or `product_data` is required. + """ + product_data: NotRequired[ + "Invoice.UpdateLinesParamsLinePriceDataProductData" + ] + """ + Data used to generate a new product object inline. One of `product` or `product_data` is required. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A non-negative integer in cents (or local equivalent) representing how much to charge. One of `unit_amount` or `unit_amount_decimal` is required. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class UpdateLinesParamsLinePriceDataProductData(TypedDict): + description: NotRequired[str] + """ + The product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes. + """ + images: NotRequired[List[str]] + """ + A list of up to 8 URLs of images for this product, meant to be displayable to the customer. + """ + metadata: NotRequired[Dict[str, str]] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + name: str + """ + The product's name, meant to be displayable to the customer. + """ + tax_code: NotRequired[str] + """ + A [tax code](https://stripe.com/docs/tax/tax-categories) ID. + """ + + class UpdateLinesParamsLineTaxAmount(TypedDict): + amount: int + """ + The amount, in cents (or local equivalent), of the tax. + """ + tax_rate_data: "Invoice.UpdateLinesParamsLineTaxAmountTaxRateData" + """ + Data to find or create a TaxRate object. + + Stripe automatically creates or reuses a TaxRate object for each tax amount. If the `tax_rate_data` exactly matches a previous value, Stripe will reuse the TaxRate object. TaxRate objects created automatically by Stripe are immediately archived, do not appear in the line item's `tax_rates`, and cannot be directly added to invoices, payments, or line items. + """ + taxable_amount: int + """ + The amount on which tax is calculated, in cents (or local equivalent). + """ + + class UpdateLinesParamsLineTaxAmountTaxRateData(TypedDict): + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + description: NotRequired[str] + """ + An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers. + """ + display_name: str + """ + The display name of the tax rate, which will be shown to users. + """ + inclusive: bool + """ + This specifies if the tax rate is inclusive or exclusive. + """ + jurisdiction: NotRequired[str] + """ + The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer's invoice. + """ + percentage: float + """ + The statutory tax rate percent. This field accepts decimal values between 0 and 100 inclusive with at most 4 decimal places. To accommodate fixed-amount taxes, set the percentage to zero. Stripe will not display zero percentages on the invoice unless the `amount` of the tax is also zero. + """ + state: NotRequired[str] + """ + [ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2:US), without country prefix. For example, "NY" for New York, United States. + """ + tax_type: NotRequired[ + Literal[ + "amusement_tax", + "communications_tax", + "gst", + "hst", + "igst", + "jct", + "lease_tax", + "pst", + "qst", + "rst", + "sales_tax", + "vat", + ] + ] + """ + The high-level tax type, such as `vat` or `sales_tax`. + """ + + class VoidInvoiceParams(RequestOptions): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + + account_country: Optional[str] + """ + The country of the business associated with this invoice, most often the business creating the invoice. + """ + account_name: Optional[str] + """ + The public name of the business associated with this invoice, most often the business creating the invoice. + """ + account_tax_ids: Optional[List[ExpandableField["TaxId"]]] + """ + The account tax IDs associated with the invoice. Only editable when the invoice is a draft. + """ + amount_due: int + """ + Final amount due at this time for this invoice. If the invoice's total is smaller than the minimum charge amount, for example, or if there is account credit that can be applied to the invoice, the `amount_due` may be 0. If there is a positive `starting_balance` for the invoice (the customer owes money), the `amount_due` will also take that into account. The charge that gets generated for the invoice will be for the amount specified in `amount_due`. + """ + amount_paid: int + """ + The amount, in cents (or local equivalent), that was paid. + """ + amount_remaining: int + """ + The difference between amount_due and amount_paid, in cents (or local equivalent). + """ + amount_shipping: int + """ + This is the sum of all the shipping amounts. + """ + application: Optional[ExpandableField["Application"]] + """ + ID of the Connect Application that created the invoice. + """ + application_fee_amount: Optional[int] + """ + The fee in cents (or local equivalent) that will be applied to the invoice and transferred to the application owner's Stripe account when the invoice is paid. + """ + attempt_count: int + """ + Number of payment attempts made for this invoice, from the perspective of the payment retry schedule. Any payment attempt counts as the first attempt, and subsequently only automatic retries increment the attempt count. In other words, manual payment attempts after the first attempt do not affect the retry schedule. If a failure is returned with a non-retryable return code, the invoice can no longer be retried unless a new payment method is obtained. Retries will continue to be scheduled, and attempt_count will continue to increment, but retries will only be executed if a new payment method is obtained. + """ + attempted: bool + """ + Whether an attempt has been made to pay the invoice. An invoice is not attempted until 1 hour after the `invoice.created` webhook, for example, so you might not want to display that invoice as unpaid to your users. + """ + auto_advance: Optional[bool] + """ + Controls whether Stripe performs [automatic collection](https://stripe.com/docs/invoicing/integration/automatic-advancement-collection) of the invoice. If `false`, the invoice's state doesn't automatically advance without an explicit action. + """ + automatic_tax: AutomaticTax + billing_reason: Optional[ + Literal[ + "automatic_pending_invoice_item_invoice", + "manual", + "quote_accept", + "subscription", + "subscription_create", + "subscription_cycle", + "subscription_threshold", + "subscription_update", + "upcoming", + ] + ] + """ + Indicates the reason why the invoice was created. + + * `manual`: Unrelated to a subscription, for example, created via the invoice editor. + * `subscription`: No longer in use. Applies to subscriptions from before May 2018 where no distinction was made between updates, cycles, and thresholds. + * `subscription_create`: A new subscription was created. + * `subscription_cycle`: A subscription advanced into a new period. + * `subscription_threshold`: A subscription reached a billing threshold. + * `subscription_update`: A subscription was updated. + * `upcoming`: Reserved for simulated invoices, per the upcoming invoice endpoint. + """ + charge: Optional[ExpandableField["Charge"]] + """ + ID of the latest charge generated for this invoice, if any. + """ collection_method: Literal["charge_automatically", "send_invoice"] """ Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay this invoice using the default source attached to the customer. When sending an invoice, Stripe will email this invoice to the customer with payment instructions. @@ -5988,6 +6431,116 @@ class VoidInvoiceParams(RequestOptions): Always true for a deleted object """ + @classmethod + def _cls_add_lines( + cls, invoice: str, **params: Unpack["Invoice.AddLinesParams"] + ) -> "Invoice": + """ + Adds multiple line items to an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + cls._static_request( + "post", + "/v1/invoices/{invoice}/add_lines".format( + invoice=sanitize_id(invoice) + ), + params=params, + ), + ) + + @overload + @staticmethod + def add_lines( + invoice: str, **params: Unpack["Invoice.AddLinesParams"] + ) -> "Invoice": + """ + Adds multiple line items to an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @overload + def add_lines( + self, **params: Unpack["Invoice.AddLinesParams"] + ) -> "Invoice": + """ + Adds multiple line items to an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @class_method_variant("_cls_add_lines") + def add_lines( # pyright: ignore[reportGeneralTypeIssues] + self, **params: Unpack["Invoice.AddLinesParams"] + ) -> "Invoice": + """ + Adds multiple line items to an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + self._request( + "post", + "/v1/invoices/{invoice}/add_lines".format( + invoice=sanitize_id(self.get("id")) + ), + params=params, + ), + ) + + @classmethod + async def _cls_add_lines_async( + cls, invoice: str, **params: Unpack["Invoice.AddLinesParams"] + ) -> "Invoice": + """ + Adds multiple line items to an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + await cls._static_request_async( + "post", + "/v1/invoices/{invoice}/add_lines".format( + invoice=sanitize_id(invoice) + ), + params=params, + ), + ) + + @overload + @staticmethod + async def add_lines_async( + invoice: str, **params: Unpack["Invoice.AddLinesParams"] + ) -> "Invoice": + """ + Adds multiple line items to an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @overload + async def add_lines_async( + self, **params: Unpack["Invoice.AddLinesParams"] + ) -> "Invoice": + """ + Adds multiple line items to an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @class_method_variant("_cls_add_lines_async") + async def add_lines_async( # pyright: ignore[reportGeneralTypeIssues] + self, **params: Unpack["Invoice.AddLinesParams"] + ) -> "Invoice": + """ + Adds multiple line items to an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + await self._request_async( + "post", + "/v1/invoices/{invoice}/add_lines".format( + invoice=sanitize_id(self.get("id")) + ), + params=params, + ), + ) + @classmethod def create(cls, **params: Unpack["Invoice.CreateParams"]) -> "Invoice": """ @@ -6568,6 +7121,116 @@ async def pay_async( # pyright: ignore[reportGeneralTypeIssues] ), ) + @classmethod + def _cls_remove_lines( + cls, invoice: str, **params: Unpack["Invoice.RemoveLinesParams"] + ) -> "Invoice": + """ + Removes multiple line items from an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + cls._static_request( + "post", + "/v1/invoices/{invoice}/remove_lines".format( + invoice=sanitize_id(invoice) + ), + params=params, + ), + ) + + @overload + @staticmethod + def remove_lines( + invoice: str, **params: Unpack["Invoice.RemoveLinesParams"] + ) -> "Invoice": + """ + Removes multiple line items from an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @overload + def remove_lines( + self, **params: Unpack["Invoice.RemoveLinesParams"] + ) -> "Invoice": + """ + Removes multiple line items from an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @class_method_variant("_cls_remove_lines") + def remove_lines( # pyright: ignore[reportGeneralTypeIssues] + self, **params: Unpack["Invoice.RemoveLinesParams"] + ) -> "Invoice": + """ + Removes multiple line items from an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + self._request( + "post", + "/v1/invoices/{invoice}/remove_lines".format( + invoice=sanitize_id(self.get("id")) + ), + params=params, + ), + ) + + @classmethod + async def _cls_remove_lines_async( + cls, invoice: str, **params: Unpack["Invoice.RemoveLinesParams"] + ) -> "Invoice": + """ + Removes multiple line items from an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + await cls._static_request_async( + "post", + "/v1/invoices/{invoice}/remove_lines".format( + invoice=sanitize_id(invoice) + ), + params=params, + ), + ) + + @overload + @staticmethod + async def remove_lines_async( + invoice: str, **params: Unpack["Invoice.RemoveLinesParams"] + ) -> "Invoice": + """ + Removes multiple line items from an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @overload + async def remove_lines_async( + self, **params: Unpack["Invoice.RemoveLinesParams"] + ) -> "Invoice": + """ + Removes multiple line items from an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @class_method_variant("_cls_remove_lines_async") + async def remove_lines_async( # pyright: ignore[reportGeneralTypeIssues] + self, **params: Unpack["Invoice.RemoveLinesParams"] + ) -> "Invoice": + """ + Removes multiple line items from an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + await self._request_async( + "post", + "/v1/invoices/{invoice}/remove_lines".format( + invoice=sanitize_id(self.get("id")) + ), + params=params, + ), + ) + @classmethod def retrieve( cls, id: str, **params: Unpack["Invoice.RetrieveParams"] @@ -6790,6 +7453,116 @@ async def upcoming_lines_async( ), ) + @classmethod + def _cls_update_lines( + cls, invoice: str, **params: Unpack["Invoice.UpdateLinesParams"] + ) -> "Invoice": + """ + Updates multiple line items on an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + cls._static_request( + "post", + "/v1/invoices/{invoice}/update_lines".format( + invoice=sanitize_id(invoice) + ), + params=params, + ), + ) + + @overload + @staticmethod + def update_lines( + invoice: str, **params: Unpack["Invoice.UpdateLinesParams"] + ) -> "Invoice": + """ + Updates multiple line items on an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @overload + def update_lines( + self, **params: Unpack["Invoice.UpdateLinesParams"] + ) -> "Invoice": + """ + Updates multiple line items on an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @class_method_variant("_cls_update_lines") + def update_lines( # pyright: ignore[reportGeneralTypeIssues] + self, **params: Unpack["Invoice.UpdateLinesParams"] + ) -> "Invoice": + """ + Updates multiple line items on an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + self._request( + "post", + "/v1/invoices/{invoice}/update_lines".format( + invoice=sanitize_id(self.get("id")) + ), + params=params, + ), + ) + + @classmethod + async def _cls_update_lines_async( + cls, invoice: str, **params: Unpack["Invoice.UpdateLinesParams"] + ) -> "Invoice": + """ + Updates multiple line items on an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + await cls._static_request_async( + "post", + "/v1/invoices/{invoice}/update_lines".format( + invoice=sanitize_id(invoice) + ), + params=params, + ), + ) + + @overload + @staticmethod + async def update_lines_async( + invoice: str, **params: Unpack["Invoice.UpdateLinesParams"] + ) -> "Invoice": + """ + Updates multiple line items on an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @overload + async def update_lines_async( + self, **params: Unpack["Invoice.UpdateLinesParams"] + ) -> "Invoice": + """ + Updates multiple line items on an invoice. This is only possible when an invoice is still a draft. + """ + ... + + @class_method_variant("_cls_update_lines_async") + async def update_lines_async( # pyright: ignore[reportGeneralTypeIssues] + self, **params: Unpack["Invoice.UpdateLinesParams"] + ) -> "Invoice": + """ + Updates multiple line items on an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + "Invoice", + await self._request_async( + "post", + "/v1/invoices/{invoice}/update_lines".format( + invoice=sanitize_id(self.get("id")) + ), + params=params, + ), + ) + @classmethod def _cls_void_invoice( cls, invoice: str, **params: Unpack["Invoice.VoidInvoiceParams"] diff --git a/stripe/_invoice_line_item.py b/stripe/_invoice_line_item.py index 4ebc11c7f..cf6691f38 100644 --- a/stripe/_invoice_line_item.py +++ b/stripe/_invoice_line_item.py @@ -129,7 +129,7 @@ class ModifyParams(RequestOptions): """ metadata: NotRequired["Literal['']|Dict[str, str]"] """ - Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. For `type=recurring` line items, the incoming metadata specified on the request is directly used to set this value, in contrast to `type=invoiceitem` line items, where any existing metadata on the invoice line is merged with the incoming data. + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. For [type=subscription](https://stripe.com/docs/api/invoices/line_item#invoice_line_item_object-type) line items, the incoming metadata specified on the request is directly used to set this value, in contrast to [type=invoiceitem](api/invoices/line_item#invoice_line_item_object-type) line items, where any existing metadata on the invoice line is merged with the incoming data. """ period: NotRequired["InvoiceLineItem.ModifyParamsPeriod"] """ diff --git a/stripe/_invoice_line_item_service.py b/stripe/_invoice_line_item_service.py index 21be17673..b17ba4214 100644 --- a/stripe/_invoice_line_item_service.py +++ b/stripe/_invoice_line_item_service.py @@ -53,7 +53,7 @@ class UpdateParams(TypedDict): """ metadata: NotRequired["Literal['']|Dict[str, str]"] """ - Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. For `type=recurring` line items, the incoming metadata specified on the request is directly used to set this value, in contrast to `type=invoiceitem` line items, where any existing metadata on the invoice line is merged with the incoming data. + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. For [type=subscription](https://stripe.com/docs/api/invoices/line_item#invoice_line_item_object-type) line items, the incoming metadata specified on the request is directly used to set this value, in contrast to [type=invoiceitem](api/invoices/line_item#invoice_line_item_object-type) line items, where any existing metadata on the invoice line is merged with the incoming data. """ period: NotRequired["InvoiceLineItemService.UpdateParamsPeriod"] """ diff --git a/stripe/_invoice_service.py b/stripe/_invoice_service.py index 6c654de69..ec8fa7c77 100644 --- a/stripe/_invoice_service.py +++ b/stripe/_invoice_service.py @@ -18,6 +18,215 @@ def __init__(self, requestor): self.line_items = InvoiceLineItemService(self._requestor) self.upcoming_lines = InvoiceUpcomingLinesService(self._requestor) + class AddLinesParams(TypedDict): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + invoice_metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + lines: List["InvoiceService.AddLinesParamsLine"] + """ + The line items to add. + """ + + class AddLinesParamsLine(TypedDict): + amount: NotRequired[int] + """ + The integer amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. If you want to apply a credit to the customer's account, pass a negative amount. + """ + description: NotRequired[str] + """ + An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. + """ + discountable: NotRequired[bool] + """ + Controls whether discounts apply to this line item. Defaults to false for prorations or negative line items, and true for all other line items. Cannot be set to true for prorations. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceService.AddLinesParamsLineDiscount]" + ] + """ + The coupons, promotion codes & existing discounts which apply to the line item. Item discounts are applied before invoice discounts. Pass an empty string to remove previously-defined discounts. + """ + invoice_item: NotRequired[str] + """ + ID of an unassigned invoice item to assign to this invoice. If not provided, a new item will be created. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + period: NotRequired["InvoiceService.AddLinesParamsLinePeriod"] + """ + The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. + """ + price: NotRequired[str] + """ + The ID of the price object. One of `price` or `price_data` is required. + """ + price_data: NotRequired["InvoiceService.AddLinesParamsLinePriceData"] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. One of `price` or `price_data` is required. + """ + quantity: NotRequired[int] + """ + Non-negative integer. The quantity of units for the line item. + """ + tax_amounts: NotRequired[ + "Literal['']|List[InvoiceService.AddLinesParamsLineTaxAmount]" + ] + """ + A list of up to 10 tax amounts for this line item. This can be useful if you calculate taxes on your own or use a third-party to calculate them. You cannot set tax amounts if any line item has [tax_rates](https://stripe.com/docs/api/invoices/line_item#invoice_line_item_object-tax_rates) or if the invoice has [default_tax_rates](https://stripe.com/docs/api/invoices/object#invoice_object-default_tax_rates) or uses [automatic tax](https://stripe.com/docs/tax/invoicing). Pass an empty string to remove previously defined tax amounts. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates which apply to the line item. When set, the `default_tax_rates` on the invoice do not apply to this line item. Pass an empty string to remove previously-defined tax rates. + """ + + class AddLinesParamsLineDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class AddLinesParamsLinePeriod(TypedDict): + end: int + """ + The end of the period, which must be greater than or equal to the start. This value is inclusive. + """ + start: int + """ + The start of the period. This value is inclusive. + """ + + class AddLinesParamsLinePriceData(TypedDict): + currency: str + """ + Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). + """ + product: NotRequired[str] + """ + The ID of the product that this price will belong to. One of `product` or `product_data` is required. + """ + product_data: NotRequired[ + "InvoiceService.AddLinesParamsLinePriceDataProductData" + ] + """ + Data used to generate a new product object inline. One of `product` or `product_data` is required. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A non-negative integer in cents (or local equivalent) representing how much to charge. One of `unit_amount` or `unit_amount_decimal` is required. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class AddLinesParamsLinePriceDataProductData(TypedDict): + description: NotRequired[str] + """ + The product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes. + """ + images: NotRequired[List[str]] + """ + A list of up to 8 URLs of images for this product, meant to be displayable to the customer. + """ + metadata: NotRequired[Dict[str, str]] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + name: str + """ + The product's name, meant to be displayable to the customer. + """ + tax_code: NotRequired[str] + """ + A [tax code](https://stripe.com/docs/tax/tax-categories) ID. + """ + + class AddLinesParamsLineTaxAmount(TypedDict): + amount: int + """ + The amount, in cents (or local equivalent), of the tax. + """ + tax_rate_data: "InvoiceService.AddLinesParamsLineTaxAmountTaxRateData" + """ + Data to find or create a TaxRate object. + + Stripe automatically creates or reuses a TaxRate object for each tax amount. If the `tax_rate_data` exactly matches a previous value, Stripe will reuse the TaxRate object. TaxRate objects created automatically by Stripe are immediately archived, do not appear in the line item's `tax_rates`, and cannot be directly added to invoices, payments, or line items. + """ + taxable_amount: int + """ + The amount on which tax is calculated, in cents (or local equivalent). + """ + + class AddLinesParamsLineTaxAmountTaxRateData(TypedDict): + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + description: NotRequired[str] + """ + An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers. + """ + display_name: str + """ + The display name of the tax rate, which will be shown to users. + """ + inclusive: bool + """ + This specifies if the tax rate is inclusive or exclusive. + """ + jurisdiction: NotRequired[str] + """ + The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer's invoice. + """ + percentage: float + """ + The statutory tax rate percent. This field accepts decimal values between 0 and 100 inclusive with at most 4 decimal places. To accommodate fixed-amount taxes, set the percentage to zero. Stripe will not display zero percentages on the invoice unless the `amount` of the tax is also zero. + """ + state: NotRequired[str] + """ + [ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2:US), without country prefix. For example, "NY" for New York, United States. + """ + tax_type: NotRequired[ + Literal[ + "amusement_tax", + "communications_tax", + "gst", + "hst", + "igst", + "jct", + "lease_tax", + "pst", + "qst", + "rst", + "sales_tax", + "vat", + ] + ] + """ + The high-level tax type, such as `vat` or `sales_tax`. + """ + class CreateParams(TypedDict): account_tax_ids: NotRequired["Literal['']|List[str]"] """ @@ -1759,6 +1968,30 @@ class PayParams(TypedDict): A payment source to be charged. The source must be the ID of a source belonging to the customer associated with the invoice being paid. """ + class RemoveLinesParams(TypedDict): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + invoice_metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + lines: List["InvoiceService.RemoveLinesParamsLine"] + """ + The line items to remove. + """ + + class RemoveLinesParamsLine(TypedDict): + behavior: Literal["delete", "unassign"] + """ + Either `delete` or `unassign`. Deleted line items are permanently deleted. Unassigned line items can be reassigned to an invoice. + """ + id: str + """ + ID of an existing line item to remove from this invoice. + """ + class RetrieveParams(TypedDict): expand: NotRequired[List[str]] """ @@ -2915,6 +3148,219 @@ class UpcomingParamsSubscriptionItemPriceDataRecurring(TypedDict): The number of intervals between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks). """ + class UpdateLinesParams(TypedDict): + expand: NotRequired[List[str]] + """ + Specifies which fields in the response should be expanded. + """ + invoice_metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. For [type=subscription](https://stripe.com/docs/api/invoices/line_item#invoice_line_item_object-type) line items, the incoming metadata specified on the request is directly used to set this value, in contrast to [type=invoiceitem](api/invoices/line_item#invoice_line_item_object-type) line items, where any existing metadata on the invoice line is merged with the incoming data. + """ + lines: List["InvoiceService.UpdateLinesParamsLine"] + """ + The line items to update. + """ + + class UpdateLinesParamsLine(TypedDict): + amount: NotRequired[int] + """ + The integer amount in cents (or local equivalent) of the charge to be applied to the upcoming invoice. If you want to apply a credit to the customer's account, pass a negative amount. + """ + description: NotRequired[str] + """ + An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking. + """ + discountable: NotRequired[bool] + """ + Controls whether discounts apply to this line item. Defaults to false for prorations or negative line items, and true for all other line items. Cannot be set to true for prorations. + """ + discounts: NotRequired[ + "Literal['']|List[InvoiceService.UpdateLinesParamsLineDiscount]" + ] + """ + The coupons, promotion codes & existing discounts which apply to the line item. Item discounts are applied before invoice discounts. Pass an empty string to remove previously-defined discounts. + """ + id: str + """ + ID of an existing line item on the invoice. + """ + metadata: NotRequired["Literal['']|Dict[str, str]"] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. For [type=subscription](https://stripe.com/docs/api/invoices/line_item#invoice_line_item_object-type) line items, the incoming metadata specified on the request is directly used to set this value, in contrast to [type=invoiceitem](api/invoices/line_item#invoice_line_item_object-type) line items, where any existing metadata on the invoice line is merged with the incoming data. + """ + period: NotRequired["InvoiceService.UpdateLinesParamsLinePeriod"] + """ + The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have [Stripe Revenue Recognition](https://stripe.com/docs/revenue-recognition) enabled, the period will be used to recognize and defer revenue. See the [Revenue Recognition documentation](https://stripe.com/docs/revenue-recognition/methodology/subscriptions-and-invoicing) for details. + """ + price: NotRequired[str] + """ + The ID of the price object. One of `price` or `price_data` is required. + """ + price_data: NotRequired[ + "InvoiceService.UpdateLinesParamsLinePriceData" + ] + """ + Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline. One of `price` or `price_data` is required. + """ + quantity: NotRequired[int] + """ + Non-negative integer. The quantity of units for the line item. + """ + tax_amounts: NotRequired[ + "Literal['']|List[InvoiceService.UpdateLinesParamsLineTaxAmount]" + ] + """ + A list of up to 10 tax amounts for this line item. This can be useful if you calculate taxes on your own or use a third-party to calculate them. You cannot set tax amounts if any line item has [tax_rates](https://stripe.com/docs/api/invoices/line_item#invoice_line_item_object-tax_rates) or if the invoice has [default_tax_rates](https://stripe.com/docs/api/invoices/object#invoice_object-default_tax_rates) or uses [automatic tax](https://stripe.com/docs/tax/invoicing). Pass an empty string to remove previously defined tax amounts. + """ + tax_rates: NotRequired["Literal['']|List[str]"] + """ + The tax rates which apply to the line item. When set, the `default_tax_rates` on the invoice do not apply to this line item. Pass an empty string to remove previously-defined tax rates. + """ + + class UpdateLinesParamsLineDiscount(TypedDict): + coupon: NotRequired[str] + """ + ID of the coupon to create a new discount for. + """ + discount: NotRequired[str] + """ + ID of an existing discount on the object (or one of its ancestors) to reuse. + """ + promotion_code: NotRequired[str] + """ + ID of the promotion code to create a new discount for. + """ + + class UpdateLinesParamsLinePeriod(TypedDict): + end: int + """ + The end of the period, which must be greater than or equal to the start. This value is inclusive. + """ + start: int + """ + The start of the period. This value is inclusive. + """ + + class UpdateLinesParamsLinePriceData(TypedDict): + currency: str + """ + Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). + """ + product: NotRequired[str] + """ + The ID of the product that this price will belong to. One of `product` or `product_data` is required. + """ + product_data: NotRequired[ + "InvoiceService.UpdateLinesParamsLinePriceDataProductData" + ] + """ + Data used to generate a new product object inline. One of `product` or `product_data` is required. + """ + tax_behavior: NotRequired[ + Literal["exclusive", "inclusive", "unspecified"] + ] + """ + Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. + """ + unit_amount: NotRequired[int] + """ + A non-negative integer in cents (or local equivalent) representing how much to charge. One of `unit_amount` or `unit_amount_decimal` is required. + """ + unit_amount_decimal: NotRequired[str] + """ + Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. + """ + + class UpdateLinesParamsLinePriceDataProductData(TypedDict): + description: NotRequired[str] + """ + The product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes. + """ + images: NotRequired[List[str]] + """ + A list of up to 8 URLs of images for this product, meant to be displayable to the customer. + """ + metadata: NotRequired[Dict[str, str]] + """ + Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. + """ + name: str + """ + The product's name, meant to be displayable to the customer. + """ + tax_code: NotRequired[str] + """ + A [tax code](https://stripe.com/docs/tax/tax-categories) ID. + """ + + class UpdateLinesParamsLineTaxAmount(TypedDict): + amount: int + """ + The amount, in cents (or local equivalent), of the tax. + """ + tax_rate_data: ( + "InvoiceService.UpdateLinesParamsLineTaxAmountTaxRateData" + ) + """ + Data to find or create a TaxRate object. + + Stripe automatically creates or reuses a TaxRate object for each tax amount. If the `tax_rate_data` exactly matches a previous value, Stripe will reuse the TaxRate object. TaxRate objects created automatically by Stripe are immediately archived, do not appear in the line item's `tax_rates`, and cannot be directly added to invoices, payments, or line items. + """ + taxable_amount: int + """ + The amount on which tax is calculated, in cents (or local equivalent). + """ + + class UpdateLinesParamsLineTaxAmountTaxRateData(TypedDict): + country: NotRequired[str] + """ + Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). + """ + description: NotRequired[str] + """ + An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers. + """ + display_name: str + """ + The display name of the tax rate, which will be shown to users. + """ + inclusive: bool + """ + This specifies if the tax rate is inclusive or exclusive. + """ + jurisdiction: NotRequired[str] + """ + The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer's invoice. + """ + percentage: float + """ + The statutory tax rate percent. This field accepts decimal values between 0 and 100 inclusive with at most 4 decimal places. To accommodate fixed-amount taxes, set the percentage to zero. Stripe will not display zero percentages on the invoice unless the `amount` of the tax is also zero. + """ + state: NotRequired[str] + """ + [ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2:US), without country prefix. For example, "NY" for New York, United States. + """ + tax_type: NotRequired[ + Literal[ + "amusement_tax", + "communications_tax", + "gst", + "hst", + "igst", + "jct", + "lease_tax", + "pst", + "qst", + "rst", + "sales_tax", + "vat", + ] + ] + """ + The high-level tax type, such as `vat` or `sales_tax`. + """ + class UpdateParams(TypedDict): account_tax_ids: NotRequired["Literal['']|List[str]"] """ @@ -3832,6 +4278,52 @@ async def upcoming_async( ), ) + def add_lines( + self, + invoice: str, + params: "InvoiceService.AddLinesParams", + options: RequestOptions = {}, + ) -> Invoice: + """ + Adds multiple line items to an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + Invoice, + self._request( + "post", + "/v1/invoices/{invoice}/add_lines".format( + invoice=sanitize_id(invoice), + ), + api_mode="V1", + base_address="api", + params=params, + options=options, + ), + ) + + async def add_lines_async( + self, + invoice: str, + params: "InvoiceService.AddLinesParams", + options: RequestOptions = {}, + ) -> Invoice: + """ + Adds multiple line items to an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + Invoice, + await self._request_async( + "post", + "/v1/invoices/{invoice}/add_lines".format( + invoice=sanitize_id(invoice), + ), + api_mode="V1", + base_address="api", + params=params, + options=options, + ), + ) + def finalize_invoice( self, invoice: str, @@ -3970,6 +4462,52 @@ async def pay_async( ), ) + def remove_lines( + self, + invoice: str, + params: "InvoiceService.RemoveLinesParams", + options: RequestOptions = {}, + ) -> Invoice: + """ + Removes multiple line items from an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + Invoice, + self._request( + "post", + "/v1/invoices/{invoice}/remove_lines".format( + invoice=sanitize_id(invoice), + ), + api_mode="V1", + base_address="api", + params=params, + options=options, + ), + ) + + async def remove_lines_async( + self, + invoice: str, + params: "InvoiceService.RemoveLinesParams", + options: RequestOptions = {}, + ) -> Invoice: + """ + Removes multiple line items from an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + Invoice, + await self._request_async( + "post", + "/v1/invoices/{invoice}/remove_lines".format( + invoice=sanitize_id(invoice), + ), + api_mode="V1", + base_address="api", + params=params, + options=options, + ), + ) + def send_invoice( self, invoice: str, @@ -4020,6 +4558,52 @@ async def send_invoice_async( ), ) + def update_lines( + self, + invoice: str, + params: "InvoiceService.UpdateLinesParams", + options: RequestOptions = {}, + ) -> Invoice: + """ + Updates multiple line items on an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + Invoice, + self._request( + "post", + "/v1/invoices/{invoice}/update_lines".format( + invoice=sanitize_id(invoice), + ), + api_mode="V1", + base_address="api", + params=params, + options=options, + ), + ) + + async def update_lines_async( + self, + invoice: str, + params: "InvoiceService.UpdateLinesParams", + options: RequestOptions = {}, + ) -> Invoice: + """ + Updates multiple line items on an invoice. This is only possible when an invoice is still a draft. + """ + return cast( + Invoice, + await self._request_async( + "post", + "/v1/invoices/{invoice}/update_lines".format( + invoice=sanitize_id(invoice), + ), + api_mode="V1", + base_address="api", + params=params, + options=options, + ), + ) + def void_invoice( self, invoice: str, diff --git a/stripe/_payment_intent.py b/stripe/_payment_intent.py index 5c8d804c3..1873cbe0b 100644 --- a/stripe/_payment_intent.py +++ b/stripe/_payment_intent.py @@ -195,6 +195,7 @@ class LastPaymentError(StripeObject): "parameters_exclusive", "payment_intent_action_required", "payment_intent_authentication_failure", + "payment_intent_fx_quote_invalid", "payment_intent_incompatible_payment_method", "payment_intent_invalid_parameter", "payment_intent_konbini_rejected_confirmation_number", diff --git a/stripe/_setup_attempt.py b/stripe/_setup_attempt.py index 7aedd8bb3..e9e72c760 100644 --- a/stripe/_setup_attempt.py +++ b/stripe/_setup_attempt.py @@ -527,6 +527,7 @@ class SetupError(StripeObject): "parameters_exclusive", "payment_intent_action_required", "payment_intent_authentication_failure", + "payment_intent_fx_quote_invalid", "payment_intent_incompatible_payment_method", "payment_intent_invalid_parameter", "payment_intent_konbini_rejected_confirmation_number", diff --git a/stripe/_setup_intent.py b/stripe/_setup_intent.py index dedeefd03..610c46d7d 100644 --- a/stripe/_setup_intent.py +++ b/stripe/_setup_intent.py @@ -180,6 +180,7 @@ class LastSetupError(StripeObject): "parameters_exclusive", "payment_intent_action_required", "payment_intent_authentication_failure", + "payment_intent_fx_quote_invalid", "payment_intent_incompatible_payment_method", "payment_intent_invalid_parameter", "payment_intent_konbini_rejected_confirmation_number", diff --git a/stripe/billing/_meter.py b/stripe/billing/_meter.py index f2fe0f0ee..e857a9950 100644 --- a/stripe/billing/_meter.py +++ b/stripe/billing/_meter.py @@ -126,7 +126,7 @@ class ListEventSummariesParams(RequestOptions): """ end_time: int """ - The timestamp from when to stop aggregating meter events (exclusive). + The timestamp from when to stop aggregating meter events (exclusive). Must be aligned with minute boundaries. """ ending_before: NotRequired[str] """ @@ -142,7 +142,7 @@ class ListEventSummariesParams(RequestOptions): """ start_time: int """ - The timestamp from when to start aggregating meter events (inclusive). + The timestamp from when to start aggregating meter events (inclusive). Must be aligned with minute boundaries. """ starting_after: NotRequired[str] """ diff --git a/stripe/billing/_meter_event_summary.py b/stripe/billing/_meter_event_summary.py index a6b1e23fc..d613e0a0c 100644 --- a/stripe/billing/_meter_event_summary.py +++ b/stripe/billing/_meter_event_summary.py @@ -20,7 +20,7 @@ class MeterEventSummary(StripeObject): """ end_time: int """ - End timestamp for this event summary (inclusive). + End timestamp for this event summary (exclusive). Must be aligned with minute boundaries. """ id: str """ @@ -40,5 +40,5 @@ class MeterEventSummary(StripeObject): """ start_time: int """ - Start timestamp for this event summary (inclusive). + Start timestamp for this event summary (inclusive). Must be aligned with minute boundaries. """ diff --git a/stripe/billing/_meter_event_summary_service.py b/stripe/billing/_meter_event_summary_service.py index 48b2cacb5..9f61f603a 100644 --- a/stripe/billing/_meter_event_summary_service.py +++ b/stripe/billing/_meter_event_summary_service.py @@ -17,7 +17,7 @@ class ListParams(TypedDict): """ end_time: int """ - The timestamp from when to stop aggregating meter events (exclusive). + The timestamp from when to stop aggregating meter events (exclusive). Must be aligned with minute boundaries. """ ending_before: NotRequired[str] """ @@ -33,7 +33,7 @@ class ListParams(TypedDict): """ start_time: int """ - The timestamp from when to start aggregating meter events (inclusive). + The timestamp from when to start aggregating meter events (inclusive). Must be aligned with minute boundaries. """ starting_after: NotRequired[str] """ diff --git a/stripe/tax/_transaction.py b/stripe/tax/_transaction.py index c4f5b90a3..4ae3ba540 100644 --- a/stripe/tax/_transaction.py +++ b/stripe/tax/_transaction.py @@ -329,6 +329,10 @@ class CreateFromCalculationParams(RequestOptions): """ Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. """ + posted_at: NotRequired[int] + """ + The Unix timestamp representing when the tax liability is assumed or reduced, which determines the liability posting period and handling in tax liability reports. The timestamp must fall within the `tax_date` and the current time, unless the `tax_date` is scheduled in advance. Defaults to the current time. + """ reference: str """ A custom order or sale identifier, such as 'myOrder_123'. Must be unique across all transactions, including reversals. @@ -465,6 +469,10 @@ class RetrieveParams(RequestOptions): """ String representing the object's type. Objects of the same type share the same value. """ + posted_at: int + """ + The Unix timestamp representing when the tax liability is assumed or reduced. + """ reference: str """ A custom unique identifier, such as 'myOrder_123'. diff --git a/stripe/tax/_transaction_service.py b/stripe/tax/_transaction_service.py index de7ec3187..d76151cb0 100644 --- a/stripe/tax/_transaction_service.py +++ b/stripe/tax/_transaction_service.py @@ -29,6 +29,10 @@ class CreateFromCalculationParams(TypedDict): """ Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. """ + posted_at: NotRequired[int] + """ + The Unix timestamp representing when the tax liability is assumed or reduced, which determines the liability posting period and handling in tax liability reports. The timestamp must fall within the `tax_date` and the current time, unless the `tax_date` is scheduled in advance. Defaults to the current time. + """ reference: str """ A custom order or sale identifier, such as 'myOrder_123'. Must be unique across all transactions, including reversals.