Skip to main content
POST
/
v1
/
attach
Attach Plan
curl --request POST \
  --url https://api.example.com/v1/attach \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "<string>",
  "product_id": "<string>",
  "entity_id": "<string>",
  "invoice": true,
  "enable_product_immediately": true,
  "finalize_invoice": true,
  "redirect_mode": "<string>",
  "success_url": "<string>",
  "new_billing_subscription": true,
  "plan_schedule": {
    "start_at": 123
  },
  "discounts": [
    {
      "coupon": "<string>",
      "promotion_code": "<string>"
    }
  ],
  "billing_behavior": "<string>",
  "options": [
    {
      "feature_id": "<string>",
      "quantity": 123
    }
  ],
  "free_trial": {
    "duration_length": 123,
    "duration_type": "<string>"
  },
  "transition_rules": {},
  "subscription_id": "<string>",
  "custom_line_items": [
    {}
  ]
}
'
{
  "customer_id": "<string>",
  "entity_id": "<string>",
  "invoice": {
    "status": "<string>",
    "stripe_id": "<string>",
    "total": 123,
    "currency": "<string>",
    "hosted_invoice_url": "<string>"
  },
  "payment_url": "<string>",
  "required_action": {
    "code": "<string>",
    "reason": "<string>"
  },
  "error": {
    "message": "<string>",
    "code": "<string>"
  }
}
Attaches a plan to a customer. Handles new subscriptions, upgrades, downgrades, and add-on products.

​
Authentication

Requires a valid API secret key in the Authorization header: 
Authorization: Bearer YOUR_SECRET_KEY

​
Request Body

​
customer_id
string
required
The ID of the customer.
​
product_id
string
required
The ID of the plan/product to attach to the customer.
​
entity_id
string
The ID of the entity, if attaching the plan to a specific entity.
​
invoice
boolean
If true, creates an invoice for the subscription. Use this for deferred payment flows.
​
enable_product_immediately
boolean
If true, enables the product immediately even if an invoice is pending payment.
​
finalize_invoice
boolean
If true, finalizes the invoice immediately. Only applicable when invoice is true.
​
redirect_mode
string
default:"always"
Controls when to redirect the customer to a checkout page. Options:
  • always: Always redirect to checkout
  • if_required: Only redirect if payment action is required
  • never: Never redirect, handle payment programmatically
​
success_url
string
URL to redirect the customer to after successful payment. Used with redirect_mode.
​
new_billing_subscription
boolean
If true, creates a new billing subscription even if the customer has an existing one.
​
plan_schedule
object
Schedule when the plan should become active.
​
start_at
number
Timestamp (in milliseconds) when the plan should start.
​
discounts
array
Array of discount objects to apply to the subscription.
​
coupon
string
Stripe coupon ID to apply.
​
promotion_code
string
Stripe promotion code to apply.
​
billing_behavior
string
Controls billing behavior for plan transitions:
  • prorate_immediately (default): Invoice line items are charged immediately
  • next_cycle_only: Do not create any charges due to the attach
​
options
array
Array of feature quantity overrides.
​
feature_id
string
The feature ID to configure.
​
quantity
number
The quantity for this feature.
​
free_trial
object
Free trial configuration for the subscription.
​
duration_length
number
Length of the trial period.
​
duration_type
string
Unit of the trial period: day, week, or month.
​
transition_rules
object
Rules for how to transition between plans.
​
subscription_id
string
Specific subscription ID to attach the plan to.
​
custom_line_items
array
Array of custom line items to add to the invoice.

​
Response

​
customer_id
string
The ID of the customer.
​
entity_id
string
The ID of the entity, if the plan was attached to an entity.
​
invoice
object
Invoice details if an invoice was created. Only present when a charge was made.
​
status
string
The status of the invoice (e.g., ‘paid’, ‘open’, ‘draft’).
​
stripe_id
string
The Stripe invoice ID.
​
total
number
The total amount of the invoice in cents.
​
currency
string
The three-letter ISO currency code (e.g., ‘usd’).
​
hosted_invoice_url
string
URL to the hosted invoice page where the customer can view and pay the invoice.
​
payment_url
string
URL to redirect the customer to complete payment. Null if no payment action is required.
​
required_action
object
Details about any action required to complete the payment. Present when the payment could not be processed automatically.
​
code
string
The type of action required to complete the payment. One of:
  • 3ds_required: 3D Secure authentication is needed
  • payment_method_required: Customer needs to add a payment method
  • payment_failed: Payment was declined
​
reason
string
A human-readable explanation of why this action is required.

​
Example Request

curl -X POST https://api.autumnai.com/v1/attach \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_123",
    "product_id": "pro_plan"
  }'

​
Example Response

{
  "customer_id": "cus_123",
  "entity_id": null,
  "invoice": {
    "status": "paid",
    "stripe_id": "in_1234567890",
    "total": 4900,
    "currency": "usd",
    "hosted_invoice_url": "https://invoice.stripe.com/i/acct_xxx/test_xxx"
  },
  "payment_url": null,
  "required_action": null
}

​
Error Responses

​
error
object
​
message
string
Human-readable error message.
​
code
string
Machine-readable error code. Common codes:
  • customer_not_found: The specified customer doesn’t exist
  • product_not_found: The specified product doesn’t exist
  • invalid_inputs: Request validation failed
  • stripe_error: Payment provider error occurred
  • customer_has_no_payment_method: Customer needs to add a payment method

​
Example Error Response

{
  "error": {
    "message": "Customer not found",
    "code": "customer_not_found"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us