Renew Subscription

{
  "data": {
    "id": "string",
    "hostId": "string",
    "contactId": "string",
    "customerEmail": "string",
    "priceId": "string",
    "quantity": 1,
    "items": [
      {
        "id": "string",
        "priceId": "string",
        "quantity": 1
      }
    ],
    "status": "incomplete",
    "currentPeriodStart": "2019-08-24T14:15:22Z",
    "currentPeriodEnd": "2019-08-24T14:15:22Z",
    "trialStart": "2019-08-24T14:15:22Z",
    "trialEnd": "2019-08-24T14:15:22Z",
    "billingCycleAnchor": "2019-08-24T14:15:22Z",
    "cancelAt": "2019-08-24T14:15:22Z",
    "cancelAtPeriodEnd": true,
    "canceledAt": "2019-08-24T14:15:22Z",
    "cancelReason": "string",
    "endedAt": "2019-08-24T14:15:22Z",
    "startedAt": "2019-08-24T14:15:22Z",
    "dunningEnabled": true,
    "firstFailureAt": "2019-08-24T14:15:22Z",
    "nextRetryAt": "2019-08-24T14:15:22Z",
    "retryCount": 9007199254740991,
    "notes": "string",
    "taxIds": [
      {
        "type": "string",
        "value": "string"
      }
    ],
    "autoCharge": true,
    "paymentDueDays": 9007199254740991,
    "taxRate": 100,
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  },
  "invoice": {
    "id": "string",
    "status": "string",
    "total": -9007199254740991,
    "currency": "string"
  }
}

export interface Response {
  data: {
    id?: string;
    hostId?: string;
    /**
     * CRM contact id; optional until linked
     */
    contactId?: string;
    /**
     * Email; allows late-linking to a contact
     */
    customerEmail?: string;
    /**
     * Primary item shortcut — mirrors items[0].priceId
     */
    priceId?: string;
    /**
     * Primary item shortcut — mirrors items[0].quantity
     */
    quantity?: number;
    /**
     * All billed lines on this subscription. Each item shares the parent sub's billing cycle (Phase 1).
     */
    items?: {
      id: string;
      priceId: string;
      quantity: number;
    }[];
    /**
     * Subscription lifecycle.
     * - incomplete: created, awaiting first payment
     * - trialing: in trial period
     * - active: paying
     * - past_due: renewal payment failed; scheduler is retrying per dunning policy
     * - canceled: terminal — clean cancellation
     * - unpaid: terminal — payment failed (retries exhausted or manual override), access revoked
     */
    status?: "incomplete" | "trialing" | "active" | "past_due" | "canceled" | "unpaid";
    currentPeriodStart?: string;
    currentPeriodEnd?: string;
    trialStart?: string;
    trialEnd?: string;
    /**
     * Absolute first-billing date; when set, the first paid cycle begins on this date
     */
    billingCycleAnchor?: string;
    /**
     * Absolute scheduled end date; the sub auto-cancels on renewal once this date passes
     */
    cancelAt?: string;
    /**
     * When true, the next renewal will cancel instead of advancing
     */
    cancelAtPeriodEnd?: boolean;
    canceledAt?: string;
    cancelReason?: string;
    endedAt?: string;
    /**
     * When status first transitioned to active
     */
    startedAt?: string;
    /**
     * When false, failed renewal payments mark the sub unpaid immediately (no retries)
     */
    dunningEnabled?: boolean;
    /**
     * When the renewal payment first failed for the current past-due cycle
     */
    firstFailureAt?: string;
    /**
     * When the dunning scheduler will attempt the next retry
     */
    nextRetryAt?: string;
    /**
     * Retries attempted on the current past-due cycle
     */
    retryCount?: number;
    /**
     * Memo forwarded onto every renewal invoice
     */
    notes?: string;
    /**
     * Host tax-ID snapshot rolled forward onto each renewal invoice
     */
    taxIds?: {
      type: string;
      value: string;
    }[];
    /**
     * When true (default), the scheduler attempts an off-session charge on renewal. When false, finalize stops at email-payment-link.
     */
    autoCharge?: boolean;
    /**
     * Days the customer has to pay each renewal invoice when autoCharge=false.
     */
    paymentDueDays?: number;
    /**
     * Single tax rate (percent) applied to every renewal invoice subtotal.
     */
    taxRate?: number;
    metadata?: {
      [k: string]: string;
    };
    createdAt?: string;
    updatedAt?: string;
  };
  /**
   * Slim ref to the invoice generated by the renewal
   */
  invoice?: {
    id: string;
    status: string;
    total: number;
    currency: string;
  };
}