Create subscription

📘
API Refs

Staging: Create subscription

Pricing Note

The final subscription price includes the base amount (gross premium from stripePriceId) plus any additional fees like serviceFee and taxes. This works like invoice pricing

Request body

Name	Type	Description	Required
effectiveDate	string	Effective date of the policy/subscription (ISO 8601)	yes
expirationDate	string	Expiration date of the policy/subscription (ISO 8601)	yes
stripeCustomerId	string	Stripe customer ID (must start with "cus_")	yes
stripePriceId	string	Stripe price ID (must start with "price_")	yes
policyholderId	number	The policyholder ID from contact catalog	yes
carrierId	number	The carrier ID from contact catalog	yes
paymentMethod	string	Payment method: "card" or "us_bank_account"	yes
isAutoRemitPremiums	boolean	Auto-remit premiums for created invoices	no
serviceFee	number	Service fee amount added to base price	no
taxes	number	Tax amount added to base price	no
commission	number	Commission amount for invoices	no
numDaysForAutoRemind	number	Days for auto-reminder notifications	no
memo	string	Custom memo prefix (max 200 chars)	no
brokerCode	string	Broker code (max 50 chars)	no
shouldBeSigned	boolean	Whether invoices should be signed	no
isCommissionVisibleForPolicyholder	boolean	Show commission to policyholder	no
mgaId	number	MGA ID	no
policyId	string	External policy ID (max 50 chars)	no
downPayment	number	Down payment amount	no
financeAmount	number	Finance amount	no
billingPortalReturnUrl	string	Return URL for Stripe billing portal (when customer exits portal)	no
checkoutSuccessUrl	string	URL to redirect to after successful payment completion (automatically appends `?isPaymentCompleted=true`)	yes
checkoutCancelUrl	string	URL to redirect to when customer cancels payment	no

Response

Success Response (201 Created)

Field	Type	Description
stripeCustomerId	string	Stripe customer ID
status	string	Subscription status (see enum values below)
invoiceId	number	Internal invoice ID for reference (nullable)
plan	object	Plan details
subscriptionPricing	object	Subscription pricing with fees breakdown
checkoutSessionUrl	string	Stripe Checkout Session URL with redirect support (nullable)
billingPortalUrl	string	Billing portal URL for subscription management (nullable)

Subscription Status Values

incomplete
incomplete_expired
trialing
active
past_due
canceled
unpaid
paused
unpaid_paused

Plan Object Structure

Field	Type	Description
stripePriceId	string	Stripe price ID
amount	number	Pre-fee price amount in cents (base price before any fees are added)
interval	string	Billing interval
intervalCount	number	Frequency multiplier

Subscription Pricing Object Structure

Field	Type	Description
baseAmount	number	Base amount before fees (gross premium) in cents
totalFees	number	Total fees applied in cents
totalAmount	number	Final total amount in cents
interval	string	Billing interval
intervalCount	number	Frequency multiplier
paymentMethod	string	Payment method used

Example Request

{
  "effectiveDate": "2024-01-01T00:00:00.000Z",
  "expirationDate": "2025-01-01T00:00:00.000Z",
  "stripeCustomerId": "cus_ExampleCustomerID123",
  "stripePriceId": "price_ExamplePriceID456",
  "policyholderId": 12345,
  "carrierId": 678,
  "paymentMethod": "card",
  "isAutoRemitPremiums": true,
  "serviceFee": 25.00,
  "taxes": 8.50,
  "commission": 150.00,
  "memo": "Auto Insurance Policy",
  "brokerCode": "BRK-2024-001",
  "shouldBeSigned": true,
  "billingPortalReturnUrl": "https://example.com/billing-portal-return",
  "checkoutSuccessUrl": "https://example.com/payment-success",
  "checkoutCancelUrl": "https://example.com/payment-cancelled"
}

Example Response

{
  "stripeCustomerId": "cus_ExampleCustomerID123",
  "status": "active",
  "invoiceId": 98765,
  "plan": {
    "stripePriceId": "price_ExamplePriceID456",
    "amount": 4999,
    "interval": "month",
    "intervalCount": 1
  },
  "checkoutSessionUrl": "https://checkout.stripe.com/c/pay/cs_test_xxx",
  "billingPortalUrl": "https://billing.stripe.com/p/session/test_xxx",
}

Important Notes

Payment Method Required: The paymentMethod field is now required and determines fee structures. Only "card" and "us_bank_account" are supported.
Customer Prerequisites: The customer must already exist in Stripe with a valid payment method before creating a subscription.
Payment URLs: The response includes multiple URL options:
- checkoutSessionUrl: For initial payment completion with redirect support
- billingPortalUrl: For ongoing subscription management
URL Redirects:
- checkoutSuccessUrl and checkoutCancelUrl control redirects during the checkout process
- The success URL will automatically have ?isPaymentCompleted=true appended as a query parameter
- billingPortalReturnUrl controls redirects when customers exit the billing portal
Invoice Integration: Subscriptions automatically create invoices in the AgentSnap system with the specified configuration.

Error Responses

400 Bad Request: Invalid subscription configuration or validation errors
401 Unauthorized: Invalid or missing authorization token
403 Forbidden: Insufficient permissions
404 Not Found: Customer or price not found