Update Subscription

PATCH

subscriptions

{id}

{
  "name": "Enterprise Plan - 2024",
  "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",
  "planId": "pln_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 and other metadata about the subscription. To change the subscription status, use the dedicated Activate or Cancel endpoints. To update pricing information, use the Update Subscription Version endpoint.

Params

string

required

The unique identifier of the subscription to update

Request

{
  "name": "Enterprise Plan - 2024",
  "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
}

string

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

string

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

string

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

datetime

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

datetime

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

integer

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

datetime

The initial date when billing should commence for this subscription

datetime

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

integer

Number of trial days before billing begins, if applicable

string

Any additional contract terms specific to this subscription

array

Links to terms of service documents that apply to this subscription

Show Terms of Service Link

string

required

The title of the document

string

required

The URL to the document

array

Files containing terms of service that apply to this subscription

Show Terms of Service File

string

required

The title of the file

string

required

The URL to the file

object

Minimum spending threshold for the subscription

Show Spending Threshold

string

required

The monetary amount for the threshold

string

required

The period for the threshold (e.g., “month”, “year”)

object

Maximum spending threshold for the subscription

Show Spending Threshold

string

required

The monetary amount for the threshold

string

required

The period for the threshold (e.g., “month”, “year”)

object

Discount applied to the subscription

Show Discount

string

required

The type of discount. Possible values: percentage, fixed

string

required

The amount of the discount - for percentage discounts, this is a percentage (e.g., “10.00” for 10%)

string

required

How long the discount applies. Possible values: monthly_rolling, fixed

integer

The duration value, required if durationType is fixed

string

The unit of the duration. Possible values: days, weeks, months, years

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

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

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

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

boolean

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

string

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

integer

The duration for renewals. Required if renewalPeriodType is fixed

string

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

string

Additional description or notes regarding the cancelation reason.

string

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

string

Template for invoice memos

string

Text to display in the footer of invoices

boolean

Whether to enable roll-up billing for this subscription. When enabled, invoices for this subscription are billed to the parent customer instead of the subscription’s own customer. Requires the customer to be part of a customer family with a parent customer configured

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",
  "planId": "pln_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
}

string

Unique identifier for the subscription

datetime

When the subscription was created in ISO 8601 format

datetime

When the subscription was last updated in ISO 8601 format

string

The organization ID that owns this subscription

string

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

string

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

string

The purchase order number provided by the customer for this subscription

string

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

integer

Number of trial days before billing begins

string

Any additional contract terms specific to this subscription

array

Links to terms of service documents that apply to this subscription

Show Terms of Service Link

string

The title of the document

string

The URL to the document

array

Files containing terms of service that apply to this subscription

Show Terms of Service File

string

The title of the file

string

The URL to the file

object

Minimum spending threshold for the subscription

Show Spending Threshold

string

The monetary amount for the threshold

string

The period for the threshold (e.g., "month", "year")

object

Maximum spending threshold for the subscription

Show Spending Threshold

string

The monetary amount for the threshold

string

The period for the threshold (e.g., "month", "year")

datetime

When the contract begins in ISO 8601 format

datetime

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

integer

The duration of the contract in the units specified by contractPeriodType

string

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

object

Discount applied to the subscription

Show Discount

string

The type of discount. Possible values: percentage, fixed

string

The amount of the discount - for percentage discounts, this is a percentage (e.g., "10.00" for 10%)

string

How long the discount applies. Possible values: monthly_rolling, fixed

integer

The duration value, required if durationType is fixed

string

The unit of the duration. Possible values: days, weeks, months, years

datetime

When the discount ends (deprecated, use calculated value)

string

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

string

The original currency if the subscription was converted from another currency

string

The rate used for currency conversion, if applicable

datetime

When the conversion rate was determined

string

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

string

ID of the plan this subscription was created from, if applicable

string

Name of the person who signed the subscription

string

Email of the person who signed the subscription

string

Job title of the person who signed the subscription

string

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

string

Additional details about the cancellation reason

datetime

When the subscription was activated

datetime

When the subscription ended

boolean

Whether invoices are automatically issued for this subscription

boolean

Whether invoices are automatically paid for this subscription

boolean

Whether invoices are sent to the customer

boolean

Whether receipts are sent to the customer

datetime

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

boolean

Whether the subscription automatically renews

string

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

integer

The duration for renewals if renewalPeriodType is fixed

array

History of subscription renewals, with details about each renewal event

datetime

The initial billing date in ISO 8601 format

datetime

The most recent billing date in ISO 8601 format

boolean

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

boolean

Whether the subscription has a generated PDF document

string

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

string

Template for invoice memos

string

Text displayed in the footer of invoices for this subscription

boolean

Whether an activation email is sent when the subscription is activated

⌘I

{
  "name": "Enterprise Plan - 2024",
  "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",
  "planId": "pln_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
}

API Reference

Billing Events & Usage Metering

Bundles

Credit Grants

Credit Notes

Customers

Invoices

Plans

Products

Refunds

Subscriptions

Subscription Versions

Wallets

Params

Request

Response

​Params

​Request

​Response

Params

Request

Response