# Retrieve quotes

Retrieves a list of quotes.

Endpoint: GET /quotes
Version: latest
Security: SecretApiKey, JWT

## Security:

  - `SecretApiKey` (unknown)
    apiKey in header REB-APIKEY

  - `JWT` (unknown)
    http bearer JWT

## Query parameters:

  - `filter` (string)
    Criteria for filtering collection items.
This field requires a special format.
Use `,` to specify multiple allowed values.
Use `;` to specify multiple fields.

For more information, see [Search filters](https://www.rebilly.com/docs/dev-docs/search-filters).

  - `sort` (array)
    Sorts and orders the collection of items. To sort in descending
order, prefix with `-`. Multiple fields can be sorted by separating each with `,`.

  - `limit` (integer)
    Limit the number of collection items to be returned.
Use `0` to return an empty collection and still receive the count of matching items in `Pagination-Total`.

  - `offset` (integer)
    Specifies the starting point within the collection of items to be returned.

  - `expand` (string)
    Expands a request to include embedded objects within the `_embedded`
property of the response. This field accepts a comma-separated list of objects.

For more information, see
[Embedded resources](https://www.rebilly.com/docs/dev-docs/expand-embedded-resources).

## Response 200:

  - `200` (unknown)
    List of quotes retrieved.

## Response 200 fields (application/json):

  - `id` (string)
    ID of the quote.
    Example: qt_01HXBZMEGPETPHJZH6V4RHBMA8

  - `type` (string, required)
    Type of the quote.
When a quote is accepted, a new order is created.
    Enum: "creation"

  - `acceptanceFulfillment` (array)
    List of `acceptanceConditions` with fulfillment status.

  - `acceptanceFulfillment.condition` (string)
    Enum: "customer", "payment", "organization"

  - `acceptanceFulfillment.isFulfilled` (boolean)

  - `isNewOrder` (boolean)
    Specifies if the order is a new order.
    Example: true

  - `invoiceId` (string)
    ID of the payment invoice.
    Example: in_0YVF9605RKC62BP14NE2R7V2XT

  - `status` (string)
    Status of the quote.
    Enum: "draft", "issued", "accepted", "rejected", "canceled", "expired"

  - `websiteId` (string, required)
    ID of the website.
A website is where an organization obtains a customer.
For more information, see [Obtain an organization ID and website ID](https://www.rebilly.com/docs/settings/organizations-and-websites/#obtain-your-organization-id-and-website-id).
    Example: web_0YV7DE4Z26DQSA1AC92FBJ7SEG

  - `customerId` (string, required)
    ID of the customer resource.
    Example: cus_0YV7DDSDD1C8DA64KHH2W33CPF

  - `order` (object, required)
    Properties of the related order.

  - `order.id` (string | null)
    ID of the related order.
    Example: ord_01HVKA5975PJBSQ1SX72G3MSZC

  - `order.items` (array, required)
    Items included in the quote.

  - `order.items.id` (string)
    ID of the quote item.
    Example: qt_itm_01HXCEQNR3F1G2A6RX6HPS3KFY

  - `order.items.type` (string, required)
    Specifies the type of order item.
    Enum: "subscription"

  - `order.items.quantity` (integer)
    Number of product units in the specified plan.
Quantity for metered billing is always 0.

  - `order.items.quantityFilled` (number | null)
    Number of filled product units.
This field is not used for metered billing plans.
    Example: 5.125

  - `order.items.plan` (any, required)
    Plan details.

  - `order.items.plan.id` (string, required)
    Unique resource ID.
    Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

  - `order.items.plan.id` (string, required)
    ID of the plan.
    Example: plan_0YV7DENSVGDBW9S71XZNNYYQ0X

  - `order.items.plan.type` (string)
    Variant of the plan.
This field is optional in create and update requests.
The variant is `one-time-sale` when both `recurringInterval` and `trial` are omitted.
If included, this field must match the applicable variant.
A mismatch results in an HTTP `422` response.
Responses always include this field.
    Enum: "one-time-sale"

  - `order.items.plan.name` (string, required)
    Name of the plan.
This name is displayed on invoices and receipts.

  - `order.items.plan.description` (string)
    Plain-text description of the plan.
This field accepts plain-text only.

  - `order.items.plan.richDescription` (string)
    Rich-text description of the plan.
This field accepts rich text formatting, such as: bold, underline, italic, and hyperlinks.

  - `order.items.plan.productId` (string, required)
    ID of the related product.
    Example: prod_0YV7DES3WPC5J8JD8QTVNZBZNZ

  - `order.items.plan.productOptions` (object | null)
    Name-value pairs that specify the product options.
    Example: {"color":"red","size":"xxl"}

  - `order.items.plan.currency` (string, required)
    Currency code in ISO 4217 format.
    Example: USD

  - `order.items.plan.currencySign` (string)
    Currency sign.

  - `order.items.plan.pricing` (object, required)
    Pricing details.

  - `order.items.plan.setup` (object | null)
    Setup fee information for the plan.

  - `order.items.plan.setup.price` (number, required)
    One-time setup fee charged when the plan starts.
Set to `0` if no setup fee applies.

  - `order.items.plan.customFields` (object)
    Use custom fields to extend a resource scheme to include custom data that is not provided as a common field.
For more information, see [Custom fields](https://www.rebilly.com/catalog/all/custom-fields).
    Example: {"foo":"bar"}

  - `order.items.plan.isActive` (boolean)
    Specifies if the plan is active.

  - `order.items.plan.revision` (integer)
    Number of times the plan is modified.
Compare this value with materialized subscription item revision values.

  - `order.items.plan.isTrialOnly` (boolean)
    Specifies if a plan is a trial that does not have recurring instructions.

  - `order.items.plan.recurringInterval` (null)
    Service interval settings.

  - `order.items.plan.trial` (null)
    Trial configuration setting.

  - `order.items.plan.createdTime` (string)
    Date and time when the resource is created.
This value is set automatically when the resource is created.

  - `order.items.plan.updatedTime` (string)
    Date and time when the resource is updated.
This value is set automatically when the resource is updated.

  - `order.items.plan._links` (array)
    Related links.

  - `order.items.plan.type` (string)
    Variant of the plan.
This field is optional in create and update requests.
The variant is `subscription` when `recurringInterval` is present.
If included, this field must match the applicable variant.
A mismatch results in an HTTP `422` response.
Responses always include this field.
    Enum: "subscription"

  - `order.items.plan.trial` (object | null)

  - `order.items.plan.trial.price` (number, required)
    Price of setting up a trial.
If your service charges a fee for a trial, specify it here.
To charge no trial fee, set this value to `0`.

  - `order.items.plan.trial.period` (object, required)
    Period information.

  - `order.items.plan.meteredBilling` (object | null)
    Use metered billing when an exact quantity is unknown.
Report usage during a service period and charge customers afterwards.
Metered billing plans must be postpaid.

  - `order.items.plan.meteredBilling.strategy` (string, required)
    Enum: "sum", "last"

  - `order.items.plan.meteredBilling.min` (number | null)
    Minimum quantity that is charged at the end of a service period regardless of reported usage.

  - `order.items.plan.meteredBilling.max` (number | null)
    Maximum quantity that is charged at the end of a service period regardless of reported usage.

  - `order.items.plan.meteredBilling.sticky` (boolean)
    When enabled, if no usage is reported during a service period,
the plan bills the last known reported quantity from a previous period instead of zero.
This is suitable for hosted or persistent resources whose usage does not change every period.
Only supported with `strategy`: `last`.
    Example: false

  - `order.items.plan.invoiceTimeShift` (object | null)
    Use invoice time shift to control the billing time.
Invoice time shift adjusts the invoice issue and due date when billing must occur before the service period changes.
Use invoice time shift in conjunction with `billingTiming` to:
- Bill immediately when the service period starts.
- Bill immediately after the service period ends.
- Bill at an interval of time before the service period starts.
- Bill at an interval of time after the service period starts.
- Bill at an interval of time before the service period ends.
- Bill at an interval of time after the service period ends.

  - `order.items.plan.invoiceTimeShift.issueTimeShift` (object)
    Calculation instruction of the billing time.
This is used in conjunction with the service period anchor to calculate
the time at which the invoice is issued. For more information, see
[Service period anchor, billing timing, and invoice time shift](https://www.rebilly.com/docs/dev-docs/subscriptions#service-period-anchor-billing-timing-and-invoice-time-shift).

  - `order.items.plan.invoiceTimeShift.dueTimeShift` (object)
    Calculation instruction of the invoice due time.
This is used in conjunction with the service period anchor to calculate when
an invoice is due for payment. For more information, see
[Service period anchor, billing timing, and invoice time shift](https://www.rebilly.com/docs/dev-docs/subscriptions#service-period-anchor-billing-timing-and-invoice-time-shift).
The sequential order of due time shift is always after the due date.

  - `order.items.plan.type` (string)
    Variant of the plan.
This field is optional in create and update requests.
The variant is `trial-only` when `trial` is present without `recurringInterval`.
If included, this field must match the applicable variant.
A mismatch results in an HTTP `422` response.
Responses always include this field.
    Enum: "trial-only"

  - `order.items.plan.trial` (object | null, required)
    Trial configuration settings.

  - `order.items.description` (string)
    Description of the quote item.
    Example: Charge per approved transaction with DCC

  - `order.items.priceDescription` (string)
    Price description of the quote item.
This value is only used for metered billing items.
    Example: 50% of the markup for approved transactions

  - `order.items.usageLimits` (any)

  - `order.items.usageLimits.softLimit` (object)
    Defines thresholds for notification purposes.
For example, to notify the customer that their usage is near the hard limit of their metered billing plan.
This notification informs the customer so that they can upgrade their plan before the hard limit is reached.
When metered usage equals or exceeds the configured soft limit, the `soft-usage-limit-reached` event is triggered.
The quantity limit applies to the larger of the reported and billed quantity.
If a minimum billable quantity results in a billed quantity that is higher than the reported quantity, the billed quantity applies to the limit.
If a maximum billable quantity results in a billed quantity that is lower than the reported quantity, the reported quantity applies to the limit.
The amount limit applies to the billed amount.
To notify the customer, a webhook and notification can be configured for this event.
This field is useful for accounting and customer success purposes.
The usage of metered billing plans can still be reported if the soft limit is reached.

  - `order.items.usageLimits.softLimit.quantity` (integer)
    Usage limit quantity.

  - `order.items.usageLimits.softLimit.amount` (number)
    Usage limit amount in the currency of the order.

  - `order.items.usageLimits.hardLimit` (object)
    Defines a limit where the customer can no longer use the service.
Hard limits are used in addition to soft limits.
When a soft limit is reached,
a customer may receive a notification
but the service can still be provided up to the hard limit value so that the customer can upgrade their plan.
When the reported usage reaches the configured limit,
a specific event is triggered.
To notify the customer in the merchant system,
or block a service,
a webhook and notification can be configured for this event.
When the total usage reaches the hard limit quantity,
or amount values,
metered billing plan usages can no longer be reported.
Plans with a minimum quantity, fixed fee, or flat stairstep bracket set a minimum billable quantity and amount.
A `quantity` value below the minimum billable quantity is invalid.
An `amount` value below the minimum billable amount is invalid.
A `0` value remains valid even on plans with minimum billing.

  - `order.items.usageLimits.hardLimit.quantity` (integer)
    Usage limit quantity.

  - `order.items.usageLimits.hardLimit.amount` (number)
    Usage limit amount in the currency of the order.

  - `order.items.usageLimits.trialLimit` (any)
    Defines a usage cap during the trial period of a subscription.
This limit is enforced only while the subscription is in its trial phase.
When the reported usage reaches the configured trial limit, an event called 'trial-usage-limit-reached' is triggered.
To notify the customer or restrict access to the service, a webhook and notification can be configured for this event.
Once the trial limit is reached, additional usage cannot be reported unless the trial ends.
    Example: 20.725

  - `order.items.quantity` (integer)
    Number of product units in the specified plan.

  - `order.autopay` (boolean)
    Specifies if payment attempts for the related order are made automatically.
If autopay is enabled, the payment is retrieved from the customer on the renewal date using the payment instrument that is set at `paymentInstrumentId`,
or the default payment instrument on the order.

  - `order.shipping` (object)
    Shipping settings.

  - `order.shipping.amount` (number, required)
    Shipping amount.

  - `order.shipping.calculator` (string, required)
    Shipping calculator.
    Enum: "manual"

  - `order.shipping.rateId` (string | null)
    ID of the shipping rate.
If this value is not set,
the cheapest applicable shipping rate is used.
    Example: shipping-123-456

  - `order.shipping.amount` (number)
    Shipping amount which is calculated from [Shipping rates](https://www.rebilly.com/catalog/all/shipping-rates).

  - `order.deliveryAddress` (any)
    Delivery address of the order.

  - `order.deliveryAddress.firstName` (string | null)
    Contact's first name.
    Example: Benjamin

  - `order.deliveryAddress.lastName` (string | null)
    Contact's last name.
    Example: Franklin

  - `order.deliveryAddress.organization` (string | null)
    Contact's organization.
    Example: Rebilly

  - `order.deliveryAddress.address` (string | null)
    First line of the contact's street address.
    Example: 36 Craven St

  - `order.deliveryAddress.address2` (string | null)
    Second line of the contact's street address.

  - `order.deliveryAddress.city` (string | null)
    Contact's city of residence.
    Example: Austin

  - `order.deliveryAddress.region` (string | null)
    Contact's region of residence.
    Example: Texas

  - `order.deliveryAddress.country` (string | null)
    Contact's country of residence in ISO 3166 alpha-2 country code.
For examples, see [ISO.org](https://www.iso.org/obp/ui/#search/code/).
    Example: GB

  - `order.deliveryAddress.postalCode` (string | null)
    Contact's postal code.
    Example: WC2N 5NF

  - `order.deliveryAddress.phoneNumbers` (array)
    List of phone numbers associated with the contact.

  - `order.deliveryAddress.phoneNumbers.label` (string, required)
    Phone number label or name.
    Example: main

  - `order.deliveryAddress.phoneNumbers.value` (string, required)
    Phone number value.
    Example: 1-512-777-0269

  - `order.deliveryAddress.phoneNumbers.primary` (boolean)
    Specifies if the phone number is the contact's primary phone number.
    Example: true

  - `order.deliveryAddress.emails` (array)
    List of email addresses associated with the contact.

  - `order.deliveryAddress.emails.label` (string, required)
    Email label or name.
    Example: main

  - `order.deliveryAddress.emails.value` (string, required)
    Email address value.
    Example: rebilly@example.com

  - `order.deliveryAddress.emails.primary` (boolean)
    Specifies if the email address is the contact's primary email address.
    Example: true

  - `order.deliveryAddress.dob` (string | null)
    Contact's date of birth in ISO-8601 `YYYY-MM-DD` format.
    Example: 1980-04-01

  - `order.deliveryAddress.jobTitle` (string | null)
    Contact's job title.
    Example: CEO

  - `order.deliveryAddress.hash` (string)
    Hash value for the contact.
Use this value to compare contacts for identical attribute values.
    Example: 056ae6d97c788b9e98b049ebafd7b229bf852221

  - `order.billingAddress` (any)
    Billing address of the order.

  - `order.startTime` (string | null)
    Date and time when the created order starts.
If this value is `null`, the quote acceptance time is used.

  - `order.isLegacy` (boolean)
    Specifies if the order is a legacy order.
If omitted when the quote is created, the value follows the order model that is used by the organization: `false` for the current order model and `true` for the legacy order model.
If omitted when the quote is updated, the value does not change.
Organizations that use the current order model cannot set this value to `true`.
    Example: true

  - `invoicePreview` (object)
    Preview of the quote invoice.

  - `invoicePreview.initialAmounts` (object)
    Total amounts of the initial invoice.

  - `invoicePreview.initialAmounts.amount` (number)
    Amount of the invoice.

  - `invoicePreview.initialAmounts.subtotalAmount` (number)
    Subtotal amount of the invoice.

  - `invoicePreview.initialAmounts.discountAmount` (number)
    Discount amount that is applied to the invoice.

  - `invoicePreview.initialAmounts.shippingAmount` (number)
    Shipping amount that is applied to the invoice.

  - `invoicePreview.initialAmounts.taxAmount` (number)
    Tax amount that is applied to the invoice.

  - `invoicePreview.recurringAmounts` (object | null)
    Total amounts of the recurring invoice.
This includes recurring items only.
If the quote does not have recurring items, the value of this field is `null`.

  - `invoicePreview.recurringAmounts.amount` (number)
    Amount of the invoice.

  - `invoicePreview.recurringAmounts.subtotalAmount` (number)
    Subtotal amount of the invoice.

  - `invoicePreview.recurringAmounts.discountAmount` (number)
    Discount amount that is applied to the invoice.

  - `invoicePreview.recurringAmounts.shippingAmount` (number)
    Shipping amount that is applied to the invoice.

  - `invoicePreview.recurringAmounts.taxAmount` (number)
    Tax amount that is applied to the invoice.

  - `invoicePreview.items` (array)
    Invoice items.

  - `invoicePreview.items.quoteItemId` (string)
    ID of the related quote item.
    Example: qt_itm_01HXCEQNR3F1G2A6RX6HPS3KFY

  - `invoicePreview.items.type` (string)
    Type of the invoice item.
    Enum: "debit", "credit"

  - `invoicePreview.items.name` (string)
    Name of the invoice item.

  - `invoicePreview.items.description` (string)
    Description of the invoice item.
    Example: Charge per approved transaction with DCC

  - `invoicePreview.items.priceDescription` (string)
    Price description of the invoice item.
    Example: 50% of the markup for approved transactions

  - `invoicePreview.items.unitPrice` (number | null)
    Unit price of the invoice item.

  - `invoicePreview.items.quantity` (integer)
    Quantity of the invoice item.

  - `invoicePreview.items.period` (string | null)
    Date interval of the invoice item.

  - `invoicePreview.items.setupUnitPrice` (number | null)
    Unit price of the invoice item.

  - `invoicePreview.items.trialUnitPrice` (number | null)
    Unit price of the invoice item.

  - `invoicePreview.items.trialPeriod` (string | null)
    Date interval of the invoice item trial.

  - `invoicePreview.items.taxAmount` (number | null)
    Tax amount of the invoice item.

  - `invoicePreview.items.setupTaxAmount` (number | null)
    Tax amount of the setup that is applied to the invoice.

  - `invoicePreview.items.trialTaxAmount` (number | null)
    Tax amount of the trial that is applied to the invoice.

  - `paymentTerms` (string)
    Payment terms for the customer which are displayed on the quote.

  - `expirationTime` (string | null)
    Date and time when the quote expires.
The default expiration time is one month from the time the quote is issued.
In a `draft` state, this field may be `null`.

  - `issuedTime` (string | null)
    Date and time when the quote is issued.

  - `acceptedTime` (string | null)
    Date and time when the quote is accepted.

  - `rejectedTime` (string | null)
    Date and time when the quote is rejected.

  - `canceledTime` (string | null)
    Date and time when the quote is canceled.

  - `redirectUrl` (string)
    URL to redirect the customer to when a quote is rejected.
The default value is the website URL.

  - `signature` (object)
    Written signature and printed organization name.

  - `signature.showWrittenSignatureLines` (boolean)
    Specifies whether to show written signature lines.

  - `signature.organizationPrintedName` (string | null)
    Printed name of the organization.

  - `tax` (object)
    Taxes.

  - `tax.calculator` (string, required)
    Type of tax calculator.
    Enum: "manual"

  - `tax.amount` (number)
    Total amount of taxes.

  - `tax.items` (array, required)
    Taxes applied.

  - `tax.items.amount` (number, required)
    Amount of the tax.

  - `tax.items.description` (string, required)
    Description of the tax.

  - `tax.items.rate` (number | null)
    Overall sales tax rate which includes state, county, city and district tax.

  - `tax.items.stateAmount` (number | null)
    Amount of sales tax to collect for the state.
    Example: 0.94

  - `tax.items.countyAmount` (number | null)
    Amount of sales tax to collect for the county.
    Example: 0.04

  - `tax.items.cityAmount` (number | null)
    Amount of sales tax to collect for the city.
    Example: 0

  - `tax.items.specialDistrictAmount` (number | null)
    Amount of sales tax to collect for the special district.
    Example: 0.38

  - `tax.items.stateRate` (number | null)
    State sales tax rate for given location.

  - `tax.items.countyRate` (number | null)
    County sales tax rate for given location.

  - `tax.items.cityRate` (number | null)
    City sales tax rate for given location.

  - `tax.items.specialDistrictRate` (number | null)
    Special district sales tax rate for given location.

  - `tax.items.jurisdictions` (object | null)
    Jurisdiction names for the invoice.

  - `tax.items.jurisdictions.country` (string | null)
    Two-letter ISO country code for the provided location.
    Example: US

  - `tax.items.jurisdictions.state` (string | null)
    Postal abbreviated state name for the provided location.
    Example: CA

  - `tax.items.jurisdictions.county` (string | null)
    County name for the provided location.
    Example: LOS ANGELES

  - `tax.items.jurisdictions.city` (string | null)
    City name for the provided location.
    Example: LOS ANGELES

  - `tax.items` (array)
    Taxes applied and calculated based on the `taxCategoryId` of the related product.

  - `couponIds` (array | null)
    List of coupons to redeem on the customer and apply to the related invoice.
For more information, see [Coupons](https://www.rebilly.com/docs/settings/coupons-and-discounts/).

  - `_links` (array)
    Related links.

  - `_links.href` (string)
    Link URL.

  - `_links.rel` (string)
    Type of link.
If the quote is issued, a customer can be redirected to the `invoicePaymentFormUrl` value
to pay the related invoice using one of the methods which are available to the customer.
    Enum: "self", "quoteAcceptanceFormUrl", "invoicePaymentFormUrl"

  - `_embedded` (object)
    Embedded objects that are requested by the `expand` query parameter.

  - `_embedded.customer` (object)

  - `_embedded.website` (object)

  - `_embedded.order` (object)

  - `_embedded.invoice` (object)

  - `type` (string, required)
    Type of the quote.
When a quote is accepted, quote items and settings are applied to the related order.
Change quotes can only be created for orders with `active` or `trial-ended` status.
For `trial-ended` orders, use this quote type to convert a trial-only order to a regular recurring order.
    Enum: "change"

  - `type` (string, required)
    Type of the quote.
When a quote is accepted, quote items and settings are applied to the order and the order is reactivated.
    Enum: "reactivation"

## Response 200 headers (application/json):

  - `Pagination-Total` (integer)
    Total number of items that match the request.
The value is independent of `limit`, including when `limit` is `0`.
    Example: 332

  - `Pagination-Limit` (integer)
    Maximum number of items per page.
    Example: 100

  - `Pagination-Offset` (integer)
    Specifies the starting point within the
collection of resource results. For example, a request with
`limit=20` retrieves and displays the first 20 results on a page. A
following request with `limit=20` and `offset=20`, retrieves the next
page of 20 results.
    Example: 2

## Response 401:

  - `401` (unknown)
    Unauthorized access.
Invalid credentials used.

## Response 401 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 403:

  - `403` (unknown)
    Access forbidden.

## Response 403 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.