> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Subscription

> Create a new subscription for a customer

Creates a new subscription. This endpoint allows you to specify all the details needed for a customer subscription, including contract terms, billing preferences, and renewal options.

To create pricing information, use the [Create Subscription Version](/api-reference/subscriptions/createSubscriptionVersion) endpoint.

## Request

<Snippet file="subscriptions-create-request.mdx" />

<ParamField body="name" type="string" required>
  The name of the subscription, e.g., "Waystar Royco - 2024"
</ParamField>

<ParamField body="accountId" type="string" required>
  The unique identifier for the customer account. This is typically an Alguna
  customer ID
</ParamField>

<ParamField body="planId" type="string">
  Optional reference to a plan ID if the subscription is based on a plan
</ParamField>

<ParamField body="description" type="string">
  A brief description of the subscription, such as "Initial contract for Waystar
  Royco"
</ParamField>

<ParamField body="purchaseOrderNumber" type="string">
  Customer's purchase order number for this subscription
</ParamField>

<ParamField body="contractPeriodType" type="string">
  The period type for the contract. Possible values: `monthly_rolling`, `fixed`
</ParamField>

<ParamField body="contractStartDate" type="datetime">
  The start date and time of the contract in ISO 8601 format. This is when the
  subscription becomes effective
</ParamField>

<ParamField body="contractDuration" type="integer">
  The duration of the contract in the units specified by contractPeriodType.
  Required if contractPeriodType is fixed
</ParamField>

<ParamField body="firstBillingDate" type="datetime">
  The initial date when billing should commence for this subscription
</ParamField>

<ParamField body="chargeOneoffPricesOnContractStart" type="boolean">
  Whether to charge one-off prices at the start of the contract rather than on
  the first billing date
</ParamField>

<ParamField body="invoiceGenerationStartDate" type="datetime">
  The date when invoice generation should begin. This can differ from the
  contract start date
</ParamField>

<ParamField body="trialPeriodDays" type="integer">
  Number of trial days before billing begins, if applicable
</ParamField>

<ParamField body="additionalTerms" type="string">
  Any additional contract terms specific to this subscription
</ParamField>

<ParamField body="termsOfServiceLinks" type="array">
  Links to terms of service documents that apply to this subscription

  <Expandable title="Terms of Service Link">
    <ParamField body="title" type="string" required>
      The title of the document
    </ParamField>

    <ParamField body="url" type="string" required>
      The URL to the document
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="termsOfServiceFiles" type="array">
  Files containing terms of service that apply to this subscription

  <Expandable title="Terms of Service File">
    <ParamField body="title" type="string" required>
      The title of the file
    </ParamField>

    <ParamField body="fileURL" type="string" required>
      The URL to the file
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="minimumSpend" type="object">
  Minimum spending threshold for the subscription

  <Expandable title="Spending Threshold">
    <ParamField body="amount" type="string" required>
      The monetary amount for the threshold
    </ParamField>

    <ParamField body="period" type="string" required>
      The period for the threshold (e.g., "month", "year")
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="maximumSpend" type="object">
  Maximum spending threshold for the subscription

  <Expandable title="Spending Threshold">
    <ParamField body="amount" type="string" required>
      The monetary amount for the threshold
    </ParamField>

    <ParamField body="period" type="string" required>
      The period for the threshold (e.g., "month", "year")
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="discount" type="object">
  Discount applied to the subscription

  <Expandable title="Discount">
    <ParamField body="discountType" type="string" required>
      The type of discount. Possible values: `percentage`, `fixed`
    </ParamField>

    <ParamField body="amount" type="string" required>
      The amount of the discount - for percentage discounts, this is a
      percentage (e.g., "10.00" for 10%)
    </ParamField>

    <ParamField body="durationType" type="string" required>
      How long the discount applies. Possible values: `monthly_rolling`, `fixed`
    </ParamField>

    <ParamField body="durationValue" type="integer">
      The duration value, required if durationType is fixed
    </ParamField>

    <ParamField body="durationUnit" type="string">
      The unit of the duration. Possible values: `days`, `weeks`, `months`,
      `years`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="currency" type="string" required>
  The currency for the subscription (e.g., "USD")
</ParamField>

<ParamField body="autoIssueInvoices" type="boolean">
  Whether to automatically issue invoices for this subscription. If not
  provided, defaults to the organization's setting or plan's setting if creating
  from a plan
</ParamField>

<ParamField body="autoPayInvoices" type="boolean">
  Whether to automatically pay invoices for this subscription. If not provided,
  defaults to the customer's setting or plan's setting if creating from a plan
</ParamField>

<ParamField body="sendInvoicesToCustomer" type="boolean">
  Whether to send invoices to the customer. If not provided, defaults to the
  organization's setting or plan's setting if creating from a plan
</ParamField>

<ParamField body="sendReceiptsToCustomer" type="boolean">
  Whether to send receipts to the customer. If not provided, defaults to the
  organization's setting or plan's setting if creating from a plan
</ParamField>

<ParamField body="autoRenew" type="boolean">
  Whether the subscription should automatically renew. If not provided, defaults
  to the plan's setting if creating from a plan
</ParamField>

<ParamField body="renewalPeriodType" type="string">
  The period type for renewals. Required if autoRenew is true. Possible values:
  `monthly_rolling`, `fixed`
</ParamField>

<ParamField body="renewalDuration" type="integer">
  The duration for renewals. Required if renewalPeriodType is fixed
</ParamField>

<ParamField body="invoicePaymentTerms" type="string">
  Payment terms for invoices. Possible values: `on_issue`, `net_7`, `net_15`,
  `net_30`, `net_60`, `net_90`, `indefinite`
</ParamField>

<ParamField body="invoiceMemoTemplate" type="string">
  Template for invoice memos
</ParamField>

<ParamField body="invoiceFooterText" type="string">
  Text to display in the footer of invoices
</ParamField>

<ParamField body="sendActivationEmail" type="boolean">
  Whether to send an activation email when the subscription is activated
</ParamField>

## Response

<Snippet file="subscriptions-response.mdx" />

<Snippet file="subscription-response-fields.mdx" />