subscription_upcoming_item : Foxy hAPI

subscription_upcoming_item

Description

A subscription upcoming item represents a single line item from a projected future subscription renewal. The upcoming items table is rebuilt daily and contains pre-materialized renewal projections for all active subscriptions, making it easy to answer questions like "what products will ship next week?" or "what revenue do we expect in April?".

Each active subscription may have multiple upcoming items per renewal date (one per product), and multiple renewal sequences projected into the future (up to 13 months or until end_date).

Access upcoming items for a specific subscription: GET /subscriptions/{id}/subscription_upcoming_items

Access all upcoming items for a store: GET /stores/{id}/subscription_upcoming_items

Interact with this resource

To interact with this resource and see it in the context of the API, you can utilise Postman or your Terminal/Console to perform requests. If you have a Foxy store, you can also use the API browser in the admin to interact with resources connected to your store.

Actions

GET: View a subscription_upcoming_item
HEAD: Get just the header response
OPTIONS: Get a response explaining which HTTP methods are supported

Properties

Property	Description	Type	Constraints
renewal_sequence	Identifies which renewal this item is projected for. 1 = the next upcoming renewal, 2 = the one after, and so on.	Integer	Read only. Positive integer.
next_transaction_date	The projected date for this renewal.	Date	Read only. YYYY-MM-DD format.
product_code	The product code for this line item.	String	Read only.
product_name	The product name for this line item.	String	Read only.
product_price	The unit price for this product at the time of projection.	Decimal	Read only.
product_quantity	The quantity of this product in the subscription.	Integer	Read only.
product_discount_amount	The line-item discount amount that will be applied to this product. Based on the product's configured discount rules at the time of projection.	Decimal	Read only.
line_item_subtotal	The projected subtotal for this line item: (product_price × product_quantity) minus product_discount_amount.	Decimal	Read only.
frequency	The subscription billing frequency for this renewal (e.g., `1m`, `2w`, `30d`).	String	Read only.
date_created	The date this projection record was last generated.	DateTime	Read only.

Note: Upcoming items are projected from the subscription's template transaction. They reflect the product configuration and discount rules at the time of daily projection, not necessarily what will be charged at the actual renewal date (items and prices may change between now and then). Projections do not include taxes or shipping.

Example Representation

{
  "_links": {
    "curies": [
        {
            "name": "fx",
            "href": "https://api.foxycart.com/rels/{rel}",
            "templated": true
        }
    ],
    "self": {
      "href": "https://api.foxycart.com/subscription_upcoming_items/55678",
      "title": "This Upcoming Item"
    },
    "fx:store": {
      "href": "https://api.foxycart.com/stores/8",
      "title": "This Store"
    },
    "fx:subscription": {
      "href": "https://api.foxycart.com/subscriptions/99",
      "title": "This Subscription"
    }
  },
  "renewal_sequence": 1,
  "next_transaction_date": "2026-04-01",
  "product_code": "COFFEE-BLEND",
  "product_name": "Monthly Coffee Blend",
  "product_price": 24.9900000000,
  "product_quantity": 2,
  "product_discount_amount": 5.00,
  "line_item_subtotal": 44.98,
  "frequency": "1m",
  "date_created": "2026-03-19T01:05:00-0700"
}

Zoomable Resources

This resource has no linked resources which can be "zoomed" in on, filtered and embedded within this resource.