# Retrieve an upcoming order invoice

Retrieves an upcoming invoice for a specified order.
An upcoming invoice is an invoice that has not been issued.
It functions as a preview of the next invoice for the order.
For more information, see [Invoices](https://www.rebilly.com/docs/dev-docs/invoices/).

Endpoint: GET /orders/{id}/upcoming-invoice
Version: latest
Security: SecretApiKey, JWT

## Security:

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

  - `JWT` (unknown)
    http bearer JWT

## Path parameters:

  - `id` (string, required)
    ID of the resource.

## Query parameters:

  - `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)
    Upcoming invoice retrieved.

## Response 200 fields (application/json):

  - `id` (string)
    ID of the upcoming invoice.
This value is persisted in the future renewal invoice.
    Example: in_0YVF9605RKC62BP14NE2R7V2XT

  - `currency` (string)
    Currency code in ISO 4217 format.
    Example: USD

  - `revision` (integer)
    Number of times the upcoming invoice data has changed.

Use the revision number when analyzing webhook data to
determine if a change should take precedence over the current
representation.

  - `items` (array)
    Upcoming invoice items array.

  - `items.id` (string)
    ID of the upcoming invoice item.
    Example: ii_0YVFDEQS2KCFTBN9HXWJFY55GV

  - `items.isInterim` (boolean)
    Specifies if the line item is added to an interim invoice.

  - `items.description` (string)
    Description of the upcoming invoice item.

  - `items.unitPrice` (number)
    Unit price of the upcoming invoice item.

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

  - `items.price` (number)
    Total price of the upcoming invoice item.

  - `items.productId` (string | null)
    ID of the product.
    Example: prod_0YV7DES3WPC5J8JD8QTVNZBZNZ

  - `items.planId` (string | null)
    ID of the plan.
    Example: plan_0YV7DENSVGDBW9S71XZNNYYQ0X

  - `items.orderId` (string)
    ID of the order.
    Example: ord_01HVKA5975PJBSQ1SX72G3MSZC

  - `items.periodStartTime` (string)
    Date and time when the billing period starts.

  - `items.periodEndTime` (string)
    Date and time when the billing period ends.

  - `items.periodNumber` (integer)
    Billing period number that is associated with the invoice item.
For example, an invoice item for a service is included in billing period number 3.
The invoice item is only applied to billing period number 3.

  - `items.tax` (object)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `items._links.rel` (string)
    Type of link.
    Enum: "self"

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

  - `amountDue` (number)
    Amount that is due on the invoice.

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

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

  - `shipping` (object)
    Shipping settings.

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

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

  - `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

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

  - `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` (array)
    Taxes applied and calculated based on the `taxCategoryId` of the related product.

  - `discounts` (array)
    Discounts applied.

  - `discounts.couponId` (string)
    ID of the coupon.
    Example: cpn_0YVCNKF81GD778N4YNVGDJK558

  - `discounts.redemptionId` (string)
    Unique resource ID.
    Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

  - `discounts.amount` (number)
    Total amount discounted by this coupon.

  - `discounts.description` (string)
    Description of the discount.

  - `discounts.context` (string)
    Context in which the discount applies.
    Enum: "items", "shipping", "items-and-shipping"

  - `issuedTime` (string)
    Read-only timestamp in ISO 8601 date-time format.

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

  - `dueTime` (string)
    Date and time when the invoice is due for payment.

## 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.
If the organization requires multi-factor authentication (MFA) and the session has not passed MFA, `error` is `mfa_required`.

## Response 403 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `error` (string)
    Message that describes why the request is forbidden.
Most responses use a descriptive message, such as `Not allowed to change security settings`.
If the organization requires multi-factor authentication (MFA) and MFA verification has not been completed for the session, this value is `mfa_required`.
If the request sets `requireMfa` to `true` and MFA verification has not been completed for the session, this value is `mfa_required_for_caller`.

  - `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 404:

  - `404` (unknown)
    Resource not found.

## Response 404 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.