List Subscriptions

GET

subscriptions

curl "https://api.alguna.io/subscriptions?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -G "https://api.alguna.io/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'filters=[{"field":"status","operator":"in","value":"active,canceled"}]' \
  --data-urlencode 'sort=updated_at:desc'

const subscriptions = await alguna.subscriptions.list({
  page: 1,
  limit: 25,
  filters: [
    { field: "status", operator: "in", value: "active,canceled" },
    { field: "account_id", operator: "eq", value: "acc_abc123" }
  ],
  sort: "updated_at:desc"
});

{
  "items": [
    {
      "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
    }
  ],
  "pageCount": 5,
  "limit": 10
}

Retrieves a paginated list of all subscriptions. You can filter and sort the results using query parameters.

Query Parameters

integer

default:"1"

The page number to retrieve (1-indexed).

integer

default:"10"

The number of subscriptions to return per page. Must be one of: 5, 10, 25, 50, or 100. Values exceeding 100 are capped automatically.

string

A JSON-encoded array of filter objects. Each filter object has the following properties:

Show Filter Object

string

required

The field to filter on. Supported fields:

Field	Description
`status`	Subscription status (`draft`, `sent`, `accepted`, `active`, `canceled`)
`account_id`	The account/customer ID
`metadata`	Metadata key-value pairs (use dot notation, e.g. `metadata.custom_key`)
`tag_ids`	Tag IDs associated with the subscription
`owner_id`	The owner/assignee user ID

string

required

The comparison operator. Supported operators:

Operator	Description	Example
`eq`	Exact match	`"value": "active"`
`in`	Matches any value in a comma-separated list	`"value": "active,canceled"`

string

required

The value to match against. For the in operator, use comma-separated values.

string

Sort specification in field:order format. Order is either asc (ascending) or desc (descending).Sortable fields: name, account_name, status, activated_at, ended_at, updated_at, contract_start_date, contract_end_date.

curl "https://api.alguna.io/subscriptions?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -G "https://api.alguna.io/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'filters=[{"field":"status","operator":"in","value":"active,canceled"}]' \
  --data-urlencode 'sort=updated_at:desc'

const subscriptions = await alguna.subscriptions.list({
  page: 1,
  limit: 25,
  filters: [
    { field: "status", operator: "in", value: "active,canceled" },
    { field: "account_id", operator: "eq", value: "acc_abc123" }
  ],
  sort: "updated_at:desc"
});

Response

{
  "items": [
    {
      "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
    }
  ],
  "pageCount": 5,
  "limit": 10
}

array

List of subscription objects.

Show Subscription Object

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

integer

Total number of pages available based on the current limit.

integer

The number of items per page used for this request.

Get SubscriptionRetrieve details of a specific subscription

⌘I

curl "https://api.alguna.io/subscriptions?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -G "https://api.alguna.io/subscriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'filters=[{"field":"status","operator":"in","value":"active,canceled"}]' \
  --data-urlencode 'sort=updated_at:desc'

const subscriptions = await alguna.subscriptions.list({
  page: 1,
  limit: 25,
  filters: [
    { field: "status", operator: "in", value: "active,canceled" },
    { field: "account_id", operator: "eq", value: "acc_abc123" }
  ],
  sort: "updated_at:desc"
});

{
  "items": [
    {
      "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
    }
  ],
  "pageCount": 5,
  "limit": 10
}

API Reference

Billing Events & Usage Metering

Bundles

Credit Grants

Credit Notes

Customers

Invoices

Plans

Products

Refunds

Subscriptions

Subscription Versions

Wallets

Query Parameters

Response

​Query Parameters

​Response

Query Parameters

Response