subscription_upcoming_item

Collection: subscription_upcoming_items

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.

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.

Required Scopes

Full store_full_access
Read subscriptions_read
Write subscriptions_write

Actions

GET View a subscription upcoming item
HEAD Get just the header response
OPTIONS Get a response explaining which HTTP methods are supported

Properties (10)

renewal_sequence Integer · Read-only

Identifies which renewal this item is projected for. 1 = the next upcoming renewal, 2 = the one after, and so on.

Positive integer.

next_transaction_date Date · Read-only

The projected date for this renewal.

Format: YYYY-MM-DD

product_code String · Read-only

The product code for this line item.

product_name String · Read-only

The product name for this line item.

product_price Decimal · Read-only

The unit price for this product at the time of projection.

product_quantity Integer · Read-only

The quantity of this product in the subscription.

product_discount_amount Decimal · Read-only

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.

line_item_subtotal Decimal · Read-only

The projected subtotal for this line item: (product_price × product_quantity) minus product_discount_amount.

frequency String · Read-only

The subscription billing frequency for this renewal (e.g., 1m, 2w, 30d).

date_created DateTime · Read-only

The date this projection record was last generated.

Link Relations (3)

self This Upcoming Item
fx:store GET PATCH PUT DELETE This Store
fx:subscription GET PATCH PUT This Subscription
https://api.foxycart.com/subscription_upcoming_items/{id}

Example Representation

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