Stripe Quotes API
A Quote is a way to model prices that you'd like to provide to a customer. Once accepted, it will automatically create an invoice, subscription or subscription schedule.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Accounts Account Quotes API
description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
contact:
email: dev-platform@stripe.com
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Quotes
paths:
/v1/quotes:
get:
description: <p>Returns a list of your quotes.</p>
operationId: GetQuotes
parameters:
- description: The ID of the customer whose quotes will be retrieved.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
- description: The status of the quote.
in: query
name: status
required: false
schema:
enum:
- accepted
- canceled
- draft
- open
type: string
x-stripeBypassValidation: true
style: form
- description: Provides a list of quotes that are associated with the specified test clock. The response will not include quotes with test clocks if this and the customer parameter is not set.
in: query
name: test_clock
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetQuotesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/QuotesResourceQuoteList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Quotes
post:
description: <p>A quote models prices and services for a customer. Default options for <code>header</code>, <code>description</code>, <code>footer</code>, and <code>expires_at</code> can be set in the dashboard via the <a href="https://dashboard.stripe.com/settings/billing/quote">quote template</a>.</p>
operationId: PostQuotes
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
application_fee_amount:
explode: true
style: deepObject
application_fee_percent:
explode: true
style: deepObject
automatic_tax:
explode: true
style: deepObject
default_tax_rates:
explode: true
style: deepObject
description:
explode: true
style: deepObject
discounts:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
footer:
explode: true
style: deepObject
from_quote:
explode: true
style: deepObject
header:
explode: true
style: deepObject
invoice_settings:
explode: true
style: deepObject
line_items:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
on_behalf_of:
explode: true
style: deepObject
subscription_data:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostQuotesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/quote'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Quotes
/v1/quotes/{quote}:
get:
description: <p>Retrieves the quote with the given ID.</p>
operationId: GetQuotesQuote
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: quote
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetQuotesQuoteRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/quote'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Quotes
post:
description: <p>A quote models prices and services for a customer.</p>
operationId: PostQuotesQuote
parameters:
- in: path
name: quote
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
application_fee_amount:
explode: true
style: deepObject
application_fee_percent:
explode: true
style: deepObject
automatic_tax:
explode: true
style: deepObject
default_tax_rates:
explode: true
style: deepObject
description:
explode: true
style: deepObject
discounts:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
footer:
explode: true
style: deepObject
header:
explode: true
style: deepObject
invoice_settings:
explode: true
style: deepObject
line_items:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
on_behalf_of:
explode: true
style: deepObject
subscription_data:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostQuotesQuoteRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/quote'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Quotes
/v1/quotes/{quote}/accept:
post:
description: <p>Accepts the specified quote.</p>
operationId: PostQuotesQuoteAccept
parameters:
- in: path
name: quote
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostQuotesQuoteAcceptRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/quote'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Quotes
/v1/quotes/{quote}/cancel:
post:
description: <p>Cancels the quote.</p>
operationId: PostQuotesQuoteCancel
parameters:
- in: path
name: quote
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostQuotesQuoteCancelRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/quote'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Quotes
/v1/quotes/{quote}/computed_upfront_line_items:
get:
description: <p>When retrieving a quote, there is an includable <a href="https://stripe.com/docs/api/quotes/object#quote_object-computed-upfront-line_items"><strong>computed.upfront.line_items</strong></a> property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of upfront line items.</p>
operationId: GetQuotesQuoteComputedUpfrontLineItems
parameters:
- description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- in: path
name: quote
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetQuotesQuoteComputedUpfrontLineItemsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/QuotesResourceListLineItems'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Quotes
/v1/quotes/{quote}/finalize:
post:
description: <p>Finalizes the quote.</p>
operationId: PostQuotesQuoteFinalize
parameters:
- in: path
name: quote
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostQuotesQuoteFinalizeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/quote'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Quotes
/v1/quotes/{quote}/line_items:
get:
description: <p>When retrieving a quote, there is an includable <strong>line_items</strong> property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.</p>
operationId: GetQuotesQuoteLineItems
parameters:
- description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- in: path
name: quote
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetQuotesQuoteLineItemsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/QuotesResourceListLineItems'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Quotes
/v1/quotes/{quote}/pdf:
get:
description: <p>Download the PDF for a finalized quote</p>
operationId: GetQuotesQuotePdf
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: quote
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetQuotesQuotePdfRequest'
required: false
responses:
'200':
content:
application/pdf:
schema:
format: binary
type: string
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Quotes
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
PostQuotesQuoteFinalizeRequest:
type: object
properties:
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
expires_at:
description: A future timestamp on which the quote will be canceled if in `open` or `draft` status. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
GetQuotesQuoteLineItemsRequest:
type: object
properties: {}
GetQuotesQuoteComputedUpfrontLineItemsRequest:
type: object
properties: {}
PostQuotesQuoteRequest:
type: object
properties:
application_fee_amount:
anyOf:
- type: integer
- enum:
- ''
type: string
description: The amount of the application fee (if any) that will be requested to be applied to the payment and transferred to the application owner's Stripe account. There cannot be any line items with recurring prices when using this field.
application_fee_percent:
anyOf:
- type: number
- enum:
- ''
type: string
description: A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account. There must be at least 1 line item with a recurring price to use this field.
automatic_tax:
description: Settings for automatic tax lookup for this quote and resulting invoices and subscriptions.
properties:
enabled:
type: boolean
required:
- enabled
title: automatic_tax_param
type: object
collection_method:
description: Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay invoices at the end of the subscription cycle or at invoice finalization using the default payment method attached to the subscription or customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically`.
enum:
- charge_automatically
- send_invoice
type: string
customer:
description: The customer for which this quote belongs to. A customer is required before finalizing the quote. Once specified, it cannot be changed.
maxLength: 5000
type: string
default_tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
description: The tax rates that will apply to any line item that does not have `tax_rates` set.
description:
anyOf:
- maxLength: 500
type: string
- enum:
- ''
type: string
description: A description that will be displayed on the quote PDF.
discounts:
anyOf:
- items:
properties:
coupon:
maxLength: 5000
type: string
discount:
maxLength: 5000
type: string
title: discounts_data_param
type: object
type: array
- enum:
- ''
type: string
description: The discounts applied to the quote. You can only set up to one discount.
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
expires_at:
description: A future timestamp on which the quote will be canceled if in `open` or `draft` status. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
footer:
anyOf:
- maxLength: 500
type: string
- enum:
- ''
type: string
description: A footer that will be displayed on the quote PDF.
header:
anyOf:
- maxLength: 50
type: string
- enum:
- ''
type: string
description: A header that will be displayed on the quote PDF.
invoice_settings:
description: All invoices will be billed using the specified settings.
properties:
days_until_due:
type: integer
title: quote_param
type: object
line_items:
description: A list of line items the customer is being quoted for. Each line item includes information about the product, the quantity, and the resulting cost.
items:
properties:
id:
maxLength: 5000
type: string
price:
maxLength: 5000
type: string
price_data:
properties:
currency:
type: string
product:
maxLength: 5000
type: string
recurring:
properties:
interval:
enum:
- day
- month
- week
- year
type: string
interval_count:
type: integer
required:
- interval
title: recurring_adhoc
type: object
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
unit_amount:
type: integer
unit_amount_decimal:
format: decimal
type: string
required:
- currency
- product
title: price_data
type: object
quantity:
type: integer
tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
- ''
type: string
title: line_item_update_params
type: object
type: array
metadata:
additionalProperties:
type: string
description: 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`.
type: object
on_behalf_of:
anyOf:
- type: string
- enum:
- ''
type: string
description: The account on behalf of which to charge.
subscription_data:
description: When creating a subscription or subscription schedule, the specified configuration data will be used. There must be at least one line item with a recurring price for a subscription or subscription schedule to be created. A subscription schedule is created if `subscription_data[effective_date]` is present and in the future, otherwise a subscription is created.
properties:
description:
anyOf:
- maxLength: 500
type: string
- enum:
- ''
type: string
effective_date:
anyOf:
- enum:
- current_period_end
maxLength: 5000
type: string
- format: unix-time
type: integer
- enum:
- ''
type: string
metadata:
additionalProperties:
type: string
type: object
trial_period_days:
anyOf:
- type: integer
- enum:
- ''
type: string
title: subscription_data_update_params
type: object
transfer_data:
anyOf:
- properties:
amount:
type: integer
amount_percent:
type: number
destination:
type: string
required:
- destination
title: transfer_data_specs
type: object
- enum:
- ''
type: string
description: The data with which to automatically create a Transfer for each of the invoices.
GetQuotesQuoteRequest:
type: object
properties: {}
PostQuotesQuoteAcceptRequest:
type: object
properties:
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
GetQuotesQuotePdfRequest:
type: object
properties: {}
QuotesResourceQuoteList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/quote'
type: array
has_more:
description: True if this list has another page of items after this one that can be fetched.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/quotes
type: string
PostQuotesRequest:
type: object
properties:
application_fee_amount:
anyOf:
- type: integer
- enum:
- ''
type: string
description: The amount of the application fee (if any) that will be requested to be applied to the payment and transferred to the application owner's Stripe account. There cannot be any line items with recurring prices when using this field.
application_fee_percent:
anyOf:
- type: number
- enum:
- ''
type: string
description: A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account. There must be at least 1 line item with a recurring price to use this field.
automatic_tax:
description: Settings for automatic tax lookup for this quote and resulting invoices and subscriptions.
properties:
enabled:
type: boolean
required:
- enabled
title: automatic_tax_param
type: object
collection_method:
description: Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay invoices at the end of the subscription cycle or at invoice finalization using the default payment method attached to the subscription or customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Defaults to `charge_automatically`.
enum:
- charge_automatically
- send_invoice
type: string
customer:
description: The customer for which this quote belongs to. A customer is required before finalizing the quote. Once specified, it cannot be changed.
maxLength: 5000
type: string
default_tax_rates:
anyOf:
- items:
maxLength: 5000
type: string
type: array
- enum:
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-quotes-api-openapi.yml