List Subscriptions

Retrieve a paginated list of subscriptions with optional filtering and sorting

GET /subscriptions

cURL

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": "[e-mail]",
      "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 [e-mail] 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

page · integer · default: "1"

The page number to retrieve (1-indexed).

limit · 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.

filters · string

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

Show Filter Object

field · 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

operator · 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"

value · string · required

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

sort · 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

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": "[e-mail]",
      "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 [e-mail] with any questions",
      "sendActivationEmail": true
    }
  ],
  "pageCount": 5,
  "limit": 10
}

items · array

List of subscription objects.

Show Subscription Object

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

termsOfServiceLinks · array

Links to terms of service documents that apply to this subscription

Show Terms of Service Link

title · string

The title of the document

url · string

The URL to the document

termsOfServiceFiles · array

Files containing terms of service that apply to this subscription

Show Terms of Service File

title · string

The title of the file

fileURL · string

The URL to the file

minimumSpend · object

Minimum spending threshold for the subscription

Show Spending Threshold

amount · string

The monetary amount for the threshold

period · string

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

maximumSpend · object

Maximum spending threshold for the subscription

Show Spending Threshold

amount · string

The monetary amount for the threshold

period · string

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

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

Show Discount

discountType · string

The type of discount. Possible values: percentage, fixed

amount · string

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

durationType · string

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

durationValue · integer

The duration value, required if durationType is fixed

durationUnit · string

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

endDate · datetime

When the discount ends (deprecated, use calculated value)

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

planId · string

ID of the plan this subscription was created from, 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

invoiceFooterText · string

Text displayed in the footer of invoices for this subscription

sendActivationEmail · boolean

Whether an activation email is sent when the subscription is activated

pageCount · integer

Total number of pages available based on the current limit.

limit · integer

The number of items per page used for this request.