Billing Events & Usage Metering
Credit Grants
Customers
Invoices
Refunds
Subscriptions
Subscription Versions
curl "https://api.alguna.io/subscriptions?page=1&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"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
}
Subscriptions
List Subscriptions
Retrieve a paginated list of subscriptions with optional filtering and sorting
GET
/
subscriptions
curl "https://api.alguna.io/subscriptions?page=1&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"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
The page number to retrieve (1-indexed).
The number of subscriptions to return per page. Must be one of:
5, 10, 25, 50, or 100. Values exceeding 100 are capped automatically.A JSON-encoded array of filter objects. Each filter object has the following properties:
Show Filter Object
Show Filter Object
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 |
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" |
The value to match against. For the
in operator, use comma-separated values.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"
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
}
List of subscription objects.
Show Subscription Object
Show Subscription Object
Unique identifier for the subscription
When the subscription was created in ISO 8601 format
When the subscription was last updated in ISO 8601 format
The organization ID that owns this subscription
The name of the subscription, e.g., "Enterprise Plan - 2024"
The customer account ID associated with this subscription. This is typically
an Alguna customer ID
The purchase order number provided by the customer for this subscription
A brief description of the subscription, such as "Annual enterprise
subscription"
Number of trial days before billing begins
Any additional contract terms specific to this subscription
When the contract begins in ISO 8601 format
When the contract ends in ISO 8601 format. Only set if contractPeriodType is
fixed
The duration of the contract in the units specified by contractPeriodType
The period type for the contract. Possible values:
monthly_rolling, fixedDiscount applied to the subscription
Show Discount
Show Discount
The type of discount. Possible values:
percentage, fixedThe amount of the discount - for percentage discounts, this is a
percentage (e.g., "10.00" for 10%)
How long the discount applies. Possible values:
monthly_rolling, fixedThe duration value, required if durationType is fixed
The unit of the duration. Possible values:
days, weeks, months,
yearsWhen the discount ends (deprecated, use calculated value)
The currency for the subscription (e.g., "USD")
The original currency if the subscription was converted from another currency
The rate used for currency conversion, if applicable
When the conversion rate was determined
Current status of the subscription. Possible values:
draft, sent,
accepted, active, canceledID of the plan this subscription was created from, if applicable
Name of the person who signed the subscription
Email of the person who signed the subscription
Job title of the person who signed the subscription
Reason for cancellation if the subscription was canceled. Possible values:
no_longer_required, moving_provider, pricing, support, features,
otherAdditional details about the cancellation reason
When the subscription was activated
When the subscription ended
Whether invoices are automatically issued for this subscription
Whether invoices are automatically paid for this subscription
Whether invoices are sent to the customer
Whether receipts are sent to the customer
When invoice generation begins in ISO 8601 format. This can differ from the
contract start date
Whether the subscription automatically renews
The period type for renewals. Possible values:
monthly_rolling, fixedThe duration for renewals if renewalPeriodType is fixed
History of subscription renewals, with details about each renewal event
The initial billing date in ISO 8601 format
The most recent billing date in ISO 8601 format
Whether one-off prices are charged at contract start rather than on the first
billing date
Whether the subscription has a generated PDF document
Payment terms for invoices. Possible values:
on_issue, net_7, net_15,
net_30, net_60, net_90, indefiniteTemplate for invoice memos
Text displayed in the footer of invoices for this subscription
Whether an activation email is sent when the subscription is activated
Total number of pages available based on the current limit.
The number of items per page used for this request.
⌘I
Assistant
Responses are generated using AI and may contain mistakes.