# Retrieve an upcoming subscription order invoice

Retrieves an upcoming invoice for a specified subscription 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.

Endpoint: GET /subscriptions/{id}/upcoming-invoice
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.

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

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

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

  - `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)
    Invoice item tax.

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

  - `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` (any)

  - `tax` (any)

  - `billingAddress` (object)
    Billing address of the invoice.

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

  - `deliveryAddress` (object)
    Delivery address of the invoice.

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

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

  - `deliveryAddress.organization` (string,null)
    Contact's organization.
    Example: "Rebilly"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `deliveryAddress.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)
    ID of the redemption.

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

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

  - `issuedTime` (string)
    Date and time when the invoice is issued.

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

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

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