PATCH
/
subscriptions
/
{id}
{
  "name": "Enterprise Plan - 2024",
  "status": "active",
  "description": "Annual enterprise subscription",
  "contractPeriodType": "fixed",
  "contractStartDate": "2024-01-01T00:00:00Z",
  "contractEndDate": "2024-12-31T23:59:59Z",
  "contractDuration": 12,
  "firstBillingDate": "2024-01-01T00:00:00Z",
  "invoiceGenerationStartDate": "2024-01-01T00:00:00Z",
  "trialPeriodDays": 30,
  "additionalTerms": "Custom terms for this enterprise client",
  "termsOfServiceLinks": [
    {
      "title": "Terms of Service",
      "url": "https://example.com/terms"
    },
    {
      "title": "Privacy Policy",
      "url": "https://example.com/privacy"
    }
  ],
  "termsOfServiceFiles": [
    {
      "title": "MSA Agreement",
      "fileURL": "https://example.com/files/msa.pdf"
    }
  ],
  "minimumSpend": {
    "amount": "10000.00",
    "period": "month"
  },
  "maximumSpend": {
    "amount": "50000.00",
    "period": "month"
  },
  "discount": {
    "discountType": "percentage",
    "amount": "10.00",
    "durationType": "fixed",
    "durationValue": 12,
    "durationUnit": "months"
  },
  "autoIssueInvoices": true,
  "autoPayInvoices": false,
  "sendInvoicesToCustomer": true,
  "sendReceiptsToCustomer": true,
  "autoRenew": true,
  "renewalPeriodType": "fixed",
  "renewalDuration": 12,
  "cancelationReason": "business_needs_changed",
  "cancelationReasonDescription": "Client restructuring their technology stack",
  "invoicePaymentTerms": "net_30",
  "invoiceMemoTemplate": "Thank you for your business with us",
  "invoiceFooterText": "Please contact billing@example.com with any questions",
  "sendActivationEmail": true
}
{
  "id": "sub_0000000000000001",
  "createdAt": "2024-01-01T12:00:00Z",
  "updatedAt": "2024-01-01T12:00:00Z",
  "organizationId": "org_0000000000000001",
  "name": "Enterprise Plan - 2024",
  "accountId": "acc_0000000000000001",
  "purchaseOrderNumber": "PO-12345",
  "description": "Annual enterprise subscription",
  "trialPeriodDays": 30,
  "additionalTerms": "Custom terms for this enterprise client",
  "termsOfServiceLinks": [
    {
      "title": "Terms of Service",
      "url": "https://example.com/terms"
    },
    {
      "title": "Privacy Policy",
      "url": "https://example.com/privacy"
    }
  ],
  "termsOfServiceFiles": [
    {
      "title": "MSA Agreement",
      "fileURL": "https://example.com/files/msa.pdf"
    }
  ],
  "minimumSpend": {
    "amount": "10000.00",
    "period": "month"
  },
  "maximumSpend": {
    "amount": "50000.00",
    "period": "month"
  },
  "contractStartDate": "2024-01-01T00:00:00Z",
  "contractEndDate": "2024-12-31T23:59:59Z",
  "contractDuration": 12,
  "contractPeriodType": "fixed",
  "discount": {
    "discountType": "percentage",
    "amount": "10.00",
    "durationType": "fixed",
    "durationValue": 12,
    "durationUnit": "months"
  },
  "currency": "USD",
  "sourceCurrency": "USD",
  "conversionRate": 1,
  "conversionRateDate": "2024-01-01T00:00:00Z",
  "status": "draft",
  "quoteTemplateId": "qt_0000000000000001",
  "signerName": "John Doe",
  "signerEmail": "john.doe@example.com",
  "signerJobTitle": "CEO",
  "cancelationReason": "no_longer_required",
  "cancelationReasonDescription": "We no longer have a need for this subscription",
  "activatedAt": "2024-01-01T00:00:00Z",
  "endedAt": "2024-12-31T23:59:59Z",
  "autoIssueInvoices": true,
  "autoPayInvoices": false,
  "sendInvoicesToCustomer": true,
  "sendReceiptsToCustomer": true,
  "invoiceGenerationStartDate": "2024-01-01T00:00:00Z",
  "autoRenew": true,
  "renewalPeriodType": "fixed",
  "renewalDuration": 12,
  "renewalHistory": [],
  "firstBillingDate": "2024-01-01T00:00:00Z",
  "lastBillingDate": "2024-12-31T23:59:59Z",
  "chargeOneoffPricesOnContractStart": true,
  "hasPDF": false,
  "invoicePaymentTerms": "net_30",
  "invoiceMemoTemplate": "Thank you for your business with us",
  "invoiceFooterText": "Please contact billing@example.com with any questions",
  "sendActivationEmail": true
}

Updates the metadata about the subscription. This endpoint allows you to update the name, status, and other metadata about the subscription.

To update pricing information, use the Update Subscription Version endpoint.

Params

id
string
required

The unique identifier of the subscription to update

Request

{
  "name": "Enterprise Plan - 2024",
  "status": "active",
  "description": "Annual enterprise subscription",
  "contractPeriodType": "fixed",
  "contractStartDate": "2024-01-01T00:00:00Z",
  "contractEndDate": "2024-12-31T23:59:59Z",
  "contractDuration": 12,
  "firstBillingDate": "2024-01-01T00:00:00Z",
  "invoiceGenerationStartDate": "2024-01-01T00:00:00Z",
  "trialPeriodDays": 30,
  "additionalTerms": "Custom terms for this enterprise client",
  "termsOfServiceLinks": [
    {
      "title": "Terms of Service",
      "url": "https://example.com/terms"
    },
    {
      "title": "Privacy Policy",
      "url": "https://example.com/privacy"
    }
  ],
  "termsOfServiceFiles": [
    {
      "title": "MSA Agreement",
      "fileURL": "https://example.com/files/msa.pdf"
    }
  ],
  "minimumSpend": {
    "amount": "10000.00",
    "period": "month"
  },
  "maximumSpend": {
    "amount": "50000.00",
    "period": "month"
  },
  "discount": {
    "discountType": "percentage",
    "amount": "10.00",
    "durationType": "fixed",
    "durationValue": 12,
    "durationUnit": "months"
  },
  "autoIssueInvoices": true,
  "autoPayInvoices": false,
  "sendInvoicesToCustomer": true,
  "sendReceiptsToCustomer": true,
  "autoRenew": true,
  "renewalPeriodType": "fixed",
  "renewalDuration": 12,
  "cancelationReason": "business_needs_changed",
  "cancelationReasonDescription": "Client restructuring their technology stack",
  "invoicePaymentTerms": "net_30",
  "invoiceMemoTemplate": "Thank you for your business with us",
  "invoiceFooterText": "Please contact billing@example.com with any questions",
  "sendActivationEmail": true
}
name
string

The name of the subscription, e.g., “Waystar Royco - 2024”

status
string

The initial status of the subscription. Possible values: draft, sent, accepted, active, canceled

description
string

A brief description of the subscription, such as “Initial contract for Waystar Royco”

contractPeriodType
string

The period type for the contract. Possible values: monthly_rolling, fixed

contractStartDate
datetime

The start date and time of the contract in ISO 8601 format. This is when the subscription becomes effective

contractEndDate
datetime

The end date and time of the contract in ISO 8601 format.

contractDuration
integer

The duration of the contract in the units specified by contractPeriodType. if contractPeriodType is fixed

firstBillingDate
datetime

The initial date when billing should commence for this subscription

invoiceGenerationStartDate
datetime

The date when invoice generation should begin. This can differ from the contract start date

trialPeriodDays
integer

Number of trial days before billing begins, if applicable

additionalTerms
string

Any additional contract terms specific to this subscription

Links to terms of service documents that apply to this subscription

termsOfServiceFiles
array

Files containing terms of service that apply to this subscription

minimumSpend
object

Minimum spending threshold for the subscription

maximumSpend
object

Maximum spending threshold for the subscription

discount
object

Discount applied to the subscription

autoIssueInvoices
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

autoPayInvoices
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

sendInvoicesToCustomer
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

sendReceiptsToCustomer
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

autoRenew
boolean

Whether the subscription should automatically renew. If not provided, defaults to the plan’s setting if creating from a plan

renewalPeriodType
string

The period type for renewals. Required if autoRenew is true. Possible values: monthly_rolling, fixed

renewalDuration
integer

The duration for renewals. Required if renewalPeriodType is fixed

cancelationReason
string

The reason for cancelation if the subscription is being canceled. Possible values depend on your organization’s configured cancelation reasons.

cancelationReasonDescription
string

Additional description or notes regarding the cancelation reason.

invoicePaymentTerms
string

Payment terms for invoices. Possible values: on_issue, net_7, net_15, net_30, net_60, net_90, indefinite

invoiceMemoTemplate
string

Template for invoice memos

Text to display in the footer of invoices

sendActivationEmail
boolean

Whether to send an activation email when the subscription is activated

Response

{
  "id": "sub_0000000000000001",
  "createdAt": "2024-01-01T12:00:00Z",
  "updatedAt": "2024-01-01T12:00:00Z",
  "organizationId": "org_0000000000000001",
  "name": "Enterprise Plan - 2024",
  "accountId": "acc_0000000000000001",
  "purchaseOrderNumber": "PO-12345",
  "description": "Annual enterprise subscription",
  "trialPeriodDays": 30,
  "additionalTerms": "Custom terms for this enterprise client",
  "termsOfServiceLinks": [
    {
      "title": "Terms of Service",
      "url": "https://example.com/terms"
    },
    {
      "title": "Privacy Policy",
      "url": "https://example.com/privacy"
    }
  ],
  "termsOfServiceFiles": [
    {
      "title": "MSA Agreement",
      "fileURL": "https://example.com/files/msa.pdf"
    }
  ],
  "minimumSpend": {
    "amount": "10000.00",
    "period": "month"
  },
  "maximumSpend": {
    "amount": "50000.00",
    "period": "month"
  },
  "contractStartDate": "2024-01-01T00:00:00Z",
  "contractEndDate": "2024-12-31T23:59:59Z",
  "contractDuration": 12,
  "contractPeriodType": "fixed",
  "discount": {
    "discountType": "percentage",
    "amount": "10.00",
    "durationType": "fixed",
    "durationValue": 12,
    "durationUnit": "months"
  },
  "currency": "USD",
  "sourceCurrency": "USD",
  "conversionRate": 1,
  "conversionRateDate": "2024-01-01T00:00:00Z",
  "status": "draft",
  "quoteTemplateId": "qt_0000000000000001",
  "signerName": "John Doe",
  "signerEmail": "john.doe@example.com",
  "signerJobTitle": "CEO",
  "cancelationReason": "no_longer_required",
  "cancelationReasonDescription": "We no longer have a need for this subscription",
  "activatedAt": "2024-01-01T00:00:00Z",
  "endedAt": "2024-12-31T23:59:59Z",
  "autoIssueInvoices": true,
  "autoPayInvoices": false,
  "sendInvoicesToCustomer": true,
  "sendReceiptsToCustomer": true,
  "invoiceGenerationStartDate": "2024-01-01T00:00:00Z",
  "autoRenew": true,
  "renewalPeriodType": "fixed",
  "renewalDuration": 12,
  "renewalHistory": [],
  "firstBillingDate": "2024-01-01T00:00:00Z",
  "lastBillingDate": "2024-12-31T23:59:59Z",
  "chargeOneoffPricesOnContractStart": true,
  "hasPDF": false,
  "invoicePaymentTerms": "net_30",
  "invoiceMemoTemplate": "Thank you for your business with us",
  "invoiceFooterText": "Please contact billing@example.com with any questions",
  "sendActivationEmail": true
}
id
string

Unique identifier for the subscription

createdAt
datetime

When the subscription was created in ISO 8601 format

updatedAt
datetime

When the subscription was last updated in ISO 8601 format

organizationId
string

The organization ID that owns this subscription

name
string

The name of the subscription, e.g., "Enterprise Plan - 2024"

accountId
string

The customer account ID associated with this subscription. This is typically an Alguna customer ID

purchaseOrderNumber
string

The purchase order number provided by the customer for this subscription

description
string

A brief description of the subscription, such as "Annual enterprise subscription"

trialPeriodDays
integer

Number of trial days before billing begins

additionalTerms
string

Any additional contract terms specific to this subscription

Links to terms of service documents that apply to this subscription

termsOfServiceFiles
array

Files containing terms of service that apply to this subscription

minimumSpend
object

Minimum spending threshold for the subscription

maximumSpend
object

Maximum spending threshold for the subscription

contractStartDate
datetime

When the contract begins in ISO 8601 format

contractEndDate
datetime

When the contract ends in ISO 8601 format. Only set if contractPeriodType is fixed

contractDuration
integer

The duration of the contract in the units specified by contractPeriodType

contractPeriodType
string

The period type for the contract. Possible values: monthly_rolling, fixed

discount
object

Discount applied to the subscription

currency
string

The currency for the subscription (e.g., "USD")

sourceCurrency
string

The original currency if the subscription was converted from another currency

conversionRate
string

The rate used for currency conversion, if applicable

conversionRateDate
datetime

When the conversion rate was determined

status
string

Current status of the subscription. Possible values: draft, sent, accepted, active, canceled

quoteTemplateId
string

ID of the quote template used, if applicable

signerName
string

Name of the person who signed the subscription

signerEmail
string

Email of the person who signed the subscription

signerJobTitle
string

Job title of the person who signed the subscription

cancelationReason
string

Reason for cancellation if the subscription was canceled. Possible values: no_longer_required, moving_provider, pricing, support, features, other

cancelationReasonDescription
string

Additional details about the cancellation reason

activatedAt
datetime

When the subscription was activated

endedAt
datetime

When the subscription ended

autoIssueInvoices
boolean

Whether invoices are automatically issued for this subscription

autoPayInvoices
boolean

Whether invoices are automatically paid for this subscription

sendInvoicesToCustomer
boolean

Whether invoices are sent to the customer

sendReceiptsToCustomer
boolean

Whether receipts are sent to the customer

invoiceGenerationStartDate
datetime

When invoice generation begins in ISO 8601 format. This can differ from the contract start date

autoRenew
boolean

Whether the subscription automatically renews

renewalPeriodType
string

The period type for renewals. Possible values: monthly_rolling, fixed

renewalDuration
integer

The duration for renewals if renewalPeriodType is fixed

renewalHistory
array

History of subscription renewals, with details about each renewal event

firstBillingDate
datetime

The initial billing date in ISO 8601 format

lastBillingDate
datetime

The most recent billing date in ISO 8601 format

chargeOneoffPricesOnContractStart
boolean

Whether one-off prices are charged at contract start rather than on the first billing date

hasPDF
boolean

Whether the subscription has a generated PDF document

invoicePaymentTerms
string

Payment terms for invoices. Possible values: on_issue, net_7, net_15, net_30, net_60, net_90, indefinite

invoiceMemoTemplate
string

Template for invoice memos

Text displayed in the footer of invoices for this subscription

sendActivationEmail
boolean

Whether an activation email is sent when the subscription is activated