> ## Documentation Index > Fetch the complete documentation index at: https://studio.assembly.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a subscription > Creates a recurring subscription for a client or company. Requires a recipient (clientId or companyId), at least one line item, and a connected payout account on the portal. The billing interval is inferred from recurring prices when present, otherwise taken from the request. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/subscriptions openapi: 3.0.0 info: contact: {} title: Assembly API version: 0.0.1 servers: - url: https://api.assembly.com security: [] paths: /v1/subscriptions: post: tags: - Subscriptions summary: Create a subscription description: >- Creates a recurring subscription for a client or company. Requires a recipient (clientId or companyId), at least one line item, and a connected payout account on the portal. The billing interval is inferred from recurring prices when present, otherwise taken from the request. operationId: create-subscription requestBody: content: application/json: schema: $ref: '#/components/schemas/subscription.CreateSubscriptionInput' description: Subscription to create required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/subscription.Subscription' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/dispatcher.Error' description: Invalid request body, recipient, interval, or line items '401': content: application/json: schema: $ref: '#/components/schemas/dispatcher.Error' description: Missing or invalid API key, or caller lacks permission '404': content: application/json: schema: $ref: '#/components/schemas/dispatcher.Error' description: Payout account, recipient, or subscription template not found '500': content: application/json: schema: $ref: '#/components/schemas/dispatcher.Error' description: Unexpected server error security: - APIKeyHeader: [] components: schemas: subscription.CreateSubscriptionInput: properties: clientId: description: >- ClientID is the client the subscription bills. Exactly one of clientId, companyId, or recipientId must be provided. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string collectionMethod: description: CollectionMethod is how invoices for the subscription are collected. enum: - sendInvoice - chargeAutomatically example: sendInvoice type: string companyId: description: >- CompanyID is the company the subscription bills. Exactly one of clientId, companyId, or recipientId must be provided. example: f0e1d2c3-b4a5-6789-0123-456789abcdef type: string currency: description: Currency is the ISO currency code. example: usd type: string daysUntilDue: description: DaysUntilDue sets the invoice due date relative to issuance. example: 30 type: integer interval: allOf: - $ref: '#/components/schemas/billingutils.BillingPeriodType' description: Interval is the billing period. example: month intervalCount: description: IntervalCount is the number of intervals between billings. example: 1 type: integer lineItems: description: >- LineItems are the subscription line items. Required unless templateId is provided, in which case the template's line items are used when omitted. Must contain at least one item when provided. items: $ref: '#/components/schemas/line_item.LineItem' minItems: 1 type: array memo: description: Memo is an optional note shown on generated invoices. example: Monthly retainer type: string paymentMethodPreferences: description: >- PaymentMethodPreferences restricts which payment methods are offered. items: $ref: '#/components/schemas/payment.PaymentMethodPreference' type: array recipientId: description: >- RecipientID is the recipient (client or company) of the subscription. Exactly one of clientId, companyId, or recipientId must be provided. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string taxPercentage: description: TaxPercentage is an optional tax rate applied to generated invoices. example: 8.25 type: number templateId: description: >- TemplateID optionally seeds the subscription from a subscription template. example: a7c3e9f1-2b4d-4e6a-8c0f-1d2e3f4a5b6c type: string type: object subscription.Subscription: properties: additionalFields: additionalProperties: true description: >- StripeObject would hold field from stripe's subscription or subscription schedule object type: object cancelledAt: description: >- CancelledAt is the RFC 3339 timestamp at which the subscription was cancelled; absent while active. example: '2024-02-20T14:05:00Z' format: date-time type: string clientId: description: ClientID is the ID of the client user the subscription bills. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string collectionMethod: description: >- CollectionMethod determines how the subscription's invoices are collected. enum: - sendInvoice - chargeAutomatically example: sendInvoice type: string companyId: description: CompanyID is the ID of the company the subscription bills. example: f0e1d2c3-b4a5-6789-0123-456789abcdef type: string createdAt: type: string creatorId: type: string currency: description: >- Currency is the ISO 4217 currency code the subscription is billed in. example: usd type: string data: type: string daysUntilDue: description: >- DaysUntilDue is the number of days a recipient has to pay an invoice when collected by sending an invoice. example: 30 type: integer fields: $ref: '#/components/schemas/billing.SubscriptionFields' filteredListIndexPkey: description: '{client_id}/INBOX_NOTIFICATION' type: string forcePaused: description: >- ForcePaused indicates the subscription was paused because the workspace plan lapsed. example: false type: boolean id: type: string identityId: type: string interval: allOf: - $ref: '#/components/schemas/billingutils.BillingPeriodType' description: Interval is the billing period the subscription recurs on. example: monthly intervalCount: description: IntervalCount is the number of intervals between each billing cycle. example: 1 type: integer lineItems: description: LineItems are the products and ad-hoc charges billed on each cycle. items: $ref: '#/components/schemas/line_item.LineItem' type: array memo: description: >- Memo is an optional note shown to the recipient on generated invoices. example: Monthly retainer type: string object: type: string paymentMethodPreferences: description: >- field is only used for platform api and should not be used anywhere else on FE/BE items: $ref: '#/components/schemas/payment.PaymentMethodPreference' type: array paymentSourceId: description: >- PaymentSourceId is the ID of the saved payment source charged for automatically-collected subscriptions. example: card_1a2b3c type: string previousAttributes: additionalProperties: true type: object recipientId: description: >- RecipientID is the ID of the client or company the subscription bills. Deprecated: use ClientID and CompanyID instead example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string ref: type: string status: description: >- Status is the current lifecycle status of the subscription, mirrored from Stripe. example: active type: string taxPercentage: description: >- TaxPercentage is the tax rate applied to the subscription, as a percentage. example: 8.25 nullable: true type: number templateId: description: >- TemplateID is the ID of the subscription template the subscription was created from, when applicable. example: a7c3e9f1-2b4d-4e6a-8c0f-1d2e3f4a5b6c type: string updatedAt: type: string type: object dispatcher.Error: properties: code: type: string data: {} message: type: string type: object billingutils.BillingPeriodType: enum: - day - week - month - quarterly - biannually - year - semiannually type: string x-enum-varnames: - BillingPeriodTypeDay - BillingPeriodTypeWeek - BillingPeriodTypeMonth - BillingPeriodTypeQuarter - BillingPeriodTypeBiannual - BillingPeriodTypeYear - BillingPeriodTypeSemiAnnually line_item.LineItem: properties: amount: description: >- Amount is the per-unit charge in the smallest currency unit (e.g. cents) for a one-off line item. Required, together with description, when priceId is absent. example: 5000 type: integer description: description: >- Description is the human-readable description of a one-off line item. Required, together with amount, when priceId is absent. example: Onboarding setup fee type: string id: type: string priceId: description: >- PriceId is the ID of the price this line item bills for. Either priceId or amount with description must be provided. example: price_1a2b3c type: string priceInterval: description: >- PriceInterval is the recurring interval of the referenced price, when the line item bills a recurring price. example: month type: string productId: description: >- ProductId is the ID of the product this line item bills for; absent for one-off charges. example: prod_1a2b3c type: string quantity: description: Quantity is the number of units billed for this line item. Required. example: 2 maximum: 1000000 minimum: 1 type: number type: type: string type: object payment.PaymentMethodPreference: properties: feePaidByClient: description: >- FeesPaidByClient reports whether the transaction fee for this method is charged to the client. example: true type: boolean type: description: Type is the payment method type this preference applies to. enum: - bankAccount - creditCard example: creditCard type: string type: object billing.SubscriptionFields: properties: absorbTransactionFees: type: boolean address: allOf: - $ref: '#/components/schemas/invoice.PaymentsAddress' description: Address stores the selected billing address from custom fields allowPaymentViaACH: type: boolean allowPaymentViaCC: type: boolean attachment: type: string cancelledAt: type: string clientUserId: type: string collectionMethod: type: string companyId: type: string currency: type: string daysUntilDue: type: integer forcePaused: description: >- ForcePaused indicates this subscription was paused due to workspace plan lapse type: boolean interval: type: string lineItems: items: $ref: '#/components/schemas/fields_models.LineItem' type: array memo: type: string paymentPreferences: allOf: - $ref: '#/components/schemas/payment.PaymentPreferences' description: new property to hold payment preferenced for the subscription prorate: type: boolean purchaseFields: allOf: - $ref: '#/components/schemas/billing.PurchaseFields' description: >- Used to store a confirmation token to automatically pay the first invoice of a subscription created from a purchase reactivatedBy: description: not set by the front-end type: string resetBillingCycle: type: boolean scheduleEndDate: type: integer scheduleIterations: type: integer scheduleStartDate: type: integer taxPercentage: type: number type: object invoice.PaymentsAddress: properties: addressLine1: description: AddressLine1 is the first line of the billing street address. example: 548 Market St type: string addressLine2: description: AddressLine2 is the second line of the billing street address. example: Suite 100 type: string city: description: City is the billing city. example: San Francisco type: string country: description: Country is the billing country. example: United States type: string fullAddress: description: FullAddress is the formatted, single-line billing address. example: 548 Market St, San Francisco, CA 94105 type: string postalCode: description: PostalCode is the billing postal or ZIP code. example: '94105' type: string region: description: Region is the billing state, province, or region. example: California type: string type: object fields_models.LineItem: properties: description: type: string id: type: string priceId: type: string productId: type: string quantity: type: number rate: type: number type: object payment.PaymentPreferences: properties: absorbTransactionFee: description: >- AbsorbTransactionFee lists the payment method types for which the internal user absorbs the transaction fee. items: enum: - bankAccount - creditCard type: string type: array paymentMethodTypes: description: >- PaymentMethodTypes lists the payment method types accepted for the portal. items: enum: - bankAccount - creditCard type: string type: array type: object billing.PurchaseFields: properties: origin: $ref: '#/components/schemas/invoice.Origin' type: object invoice.Origin: enum: - internal - payment_link - product_store type: string x-enum-varnames: - OriginInternal - OriginPaymentLink - OriginProductStore securitySchemes: APIKeyHeader: in: header name: X-API-KEY type: apiKey ````