# Retrieve upcoming subscription order invoice (deprecated)

Retrieves an upcoming invoice for a specified subscription order.
This endpoint is deprecated.
Use [Retrieve an upcoming invoice](../GetSubscriptionUpcomingInvoice) instead.

Endpoint: GET /subscriptions/{id}/upcoming-invoices
Version: latest
Security: SecretApiKey, 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 fields (application/json):

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

  - `websiteId` (string)
    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

  - `subscriptionId` (string)
    ID of the related subscription order.
    Example: sub_01HRF27SATGE4Z6PBJE6PD8328

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

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

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

  - `organizationId` (string)
    Unique organization identifier.
An organization is an entity that represents a company.
For more information, see [Obtain an organization ID](https://www.rebilly.com/docs/settings/organizations-and-websites/#obtain-your-organization-id-and-website-id).
    Example: org_0YVDM8RC7GDADADSBSMW124JA8

  - `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.subscriptionId` (string)
    ID of the order.
    Example: sub_01HRF27SATGE4Z6PBJE6PD8328

  - `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.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.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._links` (array)
    Related links.

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

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

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

  - `items._embedded.product` (object)

  - `items._embedded.plan` (object)

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

  - `billingAddress` (object)
    Contact's information.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `poNumber` (string | null)
    Purchase order number that is displayed on the invoice.
    Example: PO123456

  - `notes` (string)
    Notes for the customer that are displayed on the invoice.

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

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

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

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

  - `_links` (array)
    Related links.

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

  - `_links.rel` (string)
    Type of link.
    Enum: "self", "website", "customer", "organization", "subscription", "attachments", "leadSource"

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

  - `_embedded.customer` (object)

  - `_embedded.website` (object)

  - `_embedded.organization` (object)

  - `_embedded.leadSource` (object)

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