# 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](https://www.rebilly.com/docs/dev-docs/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](https://www.rebilly.com/docs/dev-docs/expand-embedded-resources).

## Response 200 fields

- `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.
- `tax` (object)
  Taxes.
- `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

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

- `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 MFA verification has not been completed for the session and the operation requires a confirmed session, this value is `mfa_required_for_caller`. This includes turning on `requireMfa` and resetting MFA for a user. If the organization restricts access to a list of IP addresses and the request comes from an IP address that is not in the list, this value is `ip_not_allowed`.
- `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
- `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

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