262 lines
9.4 KiB
Plaintext
262 lines
9.4 KiB
Plaintext
---
|
|
title: "Preview Attach"
|
|
openapi: "openapi POST /v1/billing.preview_attach"
|
|
---
|
|
|
|
import { DynamicParamField } from "/components/dynamic-param-field.jsx";
|
|
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
|
|
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
|
|
|
|
### Body Parameters
|
|
|
|
<DynamicParamField body="customer_id" type="string" required>
|
|
The ID of the customer to attach the plan to.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="entity_id" type="string">
|
|
The ID of the entity to attach the plan to.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="plan_id" type="string" required>
|
|
The ID of the plan.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="feature_quantities" type="object[]">
|
|
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="feature_id" type="string" required />
|
|
|
|
<DynamicParamField body="quantity" type="number" />
|
|
|
|
<DynamicParamField body="adjustable" type="boolean" />
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="version" type="number">
|
|
The version of the plan to attach.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="free_trial" type="object | null">
|
|
Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="duration_length" type="number" required />
|
|
|
|
<DynamicParamField body="duration_type" type="'day' | 'month' | 'year'" />
|
|
|
|
<DynamicParamField body="card_required" type="boolean" />
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="customize" type="object">
|
|
Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="price" type="object | null">
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="amount" type="number" required />
|
|
|
|
<DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
|
|
|
|
<DynamicParamField body="interval_count" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="items" type="object[]">
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="feature_id" type="string" required />
|
|
|
|
<DynamicParamField body="included" type="number" />
|
|
|
|
<DynamicParamField body="unlimited" type="boolean" />
|
|
|
|
<DynamicParamField body="reset" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
|
|
|
|
<DynamicParamField body="interval_count" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="price" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="amount" type="number" />
|
|
|
|
<DynamicParamField body="tiers" type="object[]">
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="to" type="number" required />
|
|
|
|
<DynamicParamField body="amount" type="number" required />
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
|
|
|
|
<DynamicParamField body="interval_count" type="number" />
|
|
|
|
<DynamicParamField body="billing_units" type="number" />
|
|
|
|
<DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'" required />
|
|
|
|
<DynamicParamField body="max_purchase" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="proration" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" required />
|
|
|
|
<DynamicParamField body="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" required />
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="rollover" type="object">
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="max" type="number" />
|
|
|
|
<DynamicParamField body="expiry_duration_type" type="'month' | 'forever'" required />
|
|
|
|
<DynamicParamField body="expiry_duration_length" type="number" />
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="invoice_mode" type="object">
|
|
Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="enabled" type="boolean" required>
|
|
When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="enable_plan_immediately" type="boolean">
|
|
If true, enables the plan immediately even though the invoice is not paid yet.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="finalize" type="boolean">
|
|
If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'">
|
|
How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="discounts" type="object[]">
|
|
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
|
|
<Expandable title="properties">
|
|
<DynamicParamField body="reward_id" type="string">
|
|
The ID of the reward to apply as a discount.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="promotion_code" type="string">
|
|
The promotion code to apply as a discount.
|
|
</DynamicParamField>
|
|
|
|
</Expandable>
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="success_url" type="string">
|
|
URL to redirect to after successful checkout.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="new_billing_subscription" type="boolean">
|
|
Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
|
|
</DynamicParamField>
|
|
|
|
<DynamicParamField body="plan_schedule" type="'immediate' | 'end_of_cycle'">
|
|
When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
|
|
</DynamicParamField>
|
|
|
|
|
|
### Response
|
|
|
|
<DynamicResponseField name="customer_id" type="string">
|
|
The ID of the customer.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="line_items" type="object[]">
|
|
List of line items for the current billing period.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="title" type="string">
|
|
The title of the line item.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="description" type="string">
|
|
A detailed description of the line item.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="amount" type="number">
|
|
The amount in cents for this line item.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="discounts" type="object[]">
|
|
List of discounts applied to this line item.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="amountOff" type="number" />
|
|
|
|
<DynamicResponseField name="percentOff" type="number" />
|
|
|
|
<DynamicResponseField name="stripeCouponId" type="string" />
|
|
|
|
<DynamicResponseField name="couponName" type="string" />
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="total" type="number">
|
|
The total amount in cents for the current billing period.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="currency" type="string">
|
|
The three-letter ISO currency code (e.g., 'usd').
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="next_cycle" type="object">
|
|
Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
|
|
<Expandable title="properties">
|
|
<DynamicResponseField name="starts_at" type="number">
|
|
Unix timestamp (milliseconds) when the next billing cycle starts.
|
|
</DynamicResponseField>
|
|
|
|
<DynamicResponseField name="total" type="number">
|
|
The total amount in cents for the next cycle.
|
|
</DynamicResponseField>
|
|
|
|
</Expandable>
|
|
</DynamicResponseField>
|
|
|
|
|
|
<ResponseExample>
|
|
```json 200
|
|
{
|
|
"customerId": "charles",
|
|
"lineItems": [
|
|
{
|
|
"title": "Pro seed",
|
|
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
|
|
"amount": 20,
|
|
"discounts": []
|
|
}
|
|
],
|
|
"total": 20,
|
|
"currency": "usd"
|
|
}
|
|
```
|
|
</ResponseExample>
|