Subscriptions Queries

Query recurring subscriptions, billing cycles, and customer assignments.

Subscription — Returns a single recurring subscription by id

GraphQL

query GetSubscription($id: ID!) {
  Subscription(id: $id) {
    id
    label
    status
    frequency_unit
    frequency_interval
    starts_at
    ends_at
    next_run_at
    total
    customer { id label }
    line_items {
      id
      variant { id label }
      quantity
      price
    }
    runs {
      paginatorInfo { total }
      data {
        id
        run_at
        status
        invoice { id label }
      }
    }
  }
}

Subscriptions — Returns a paginated list of subscriptions with sorting and filters

GraphQL

query Subscriptions(
  $where: QuerySubscriptionsWhereWhereConditions,
  $orderBy: [QuerySubscriptionsOrderByOrderByClause!],
  $search: String,
  $first: Int,
  $page: Int
) {
  Subscriptions(
    where: $where,
    orderBy: $orderBy,
    search: $search,
    first: $first,
    page: $page
  ) {
    paginatorInfo {
      total
      currentPage
    }
    data {
      id
      label
      status
      next_run_at
      total
      customer { id label }
    }
  }
}

SubscriptionRuns — Returns a list of subscription execution history

GraphQL

query SubscriptionRuns(
  $where: QuerySubscriptionRunsWhereWhereConditions,
  $orderBy: [QuerySubscriptionRunsOrderByOrderByClause!],
  $first: Int,
  $page: Int
) {
  SubscriptionRuns(
    where: $where,
    orderBy: $orderBy,
    first: $first,
    page: $page
  ) {
    paginatorInfo { total }
    data {
      id
      run_at
      status
      subscription { id label }
      invoice { id label }
    }
  }
}

SubscriptionRunInvoices — Returns a paginated list of invoice allocations for subscription runs

GraphQL

query SubscriptionRunInvoices(
  $where: QuerySubscriptionRunInvoicesWhereWhereConditions,
  $orderBy: [QuerySubscriptionRunInvoicesOrderByOrderByClause!],
  $first: Int,
  $page: Int
) {
  SubscriptionRunInvoices(
    where: $where,
    orderBy: $orderBy,
    first: $first,
    page: $page
  ) {
    paginatorInfo { total }
    data {
      id
      subscription_run_id
      subscription_customer_id
      status
      error
      is_prorata
      prorata_ratio
      run { id run_at status }
      invoice { id label }
    }
  }
}

Filters: id, status, subscription_run_id, subscription_customer_id, subscription_id, run_at, customer_id, customer_label, created_at, updated_at.

SubscriptionCustomers — Returns a paginated list of customers linked to subscriptions

GraphQL

query SubscriptionCustomers(
  $where: QuerySubscriptionCustomersWhereWhereConditions,
  $orderBy: [QuerySubscriptionCustomersOrderByOrderByClause!],
  $first: Int,
  $page: Int
) {
  SubscriptionCustomers(
    where: $where,
    orderBy: $orderBy,
    first: $first,
    page: $page
  ) {
    paginatorInfo { total }
    data {
      id
      subscription_id
      customer_id
      status
      joined_at
      left_at
      discount
      discount_type
      customer { id label }
      subscription { id label }
    }
  }
}

Filters: id, subscription_id, customer_id, status, joined_at, left_at, customer_label, created_at, updated_at.

---

Available fields

Subscription

Field	Type	Description
id	Int	Unique identifier.
label	String	Subscription reference number.
status	SubscriptionStatus	Current status.
frequency_unit	SubscriptionFrequencyUnit	Frequency period (day, week, month, year).
frequency_interval	Int	Interval between runs.
max_cycles	Int	Maximum number of occurrences.
starts_at	Date	Start date.
ends_at	Date	End date.
next_run_at	Date	Next scheduled execution.
auto_create_shipping_order	Boolean	Create shipment automatically.
invoice_as_draft	Boolean	Create invoice as draft.
currency	Currency	Billing currency.
exchange_rate	Float	Exchange rate for currency conversion.
tax_type	TaxType	Tax calculation method.
default_discount	Float	Default discount rate.
discount_type	DiscountType	Discount type (amount or percentage).
total_units	Float	Total quantity per run.
subtotal	Float	Subtotal per run.
total_without_tax	Float	Total before taxes.
total_ecotax	Float	Total ecotaxes.
total	Float	Grand total per run.
total_taxes	[DocumentTaxRate]	List of taxes applied.
notes	String	Public notes for documents.
internal_notes	String	Private notes.
for_the_attention_of	String	Specific recipient name.
external_reference	String	Merchant internal reference.
created_at	DateTime	Creation time.
updated_at	DateTime	Last update time.
customer	Customer	Associated customer.
price_level	PriceLevel	Applied price level.
account_representative	AccountRepresentative	Assigned representative.
season	Season	Associated season.
invoice_pdf_template	PdfTemplate	Template for invoices.
shipping_order_pdf_template	PdfTemplate	Template for shipping orders.
billing_address	Address	Default billing address.
shipping_address	Address	Default shipping address.
line_items	[LineItemSubscription]	List of recurring items.
runs	[SubscriptionRun]	Execution history.
custom_fields	[EntityCustomField]	Custom fields for this entity.

---

Filters

Subscriptions Filters

The following fields can be used in the where parameter:

id, label, status, next_run_at, created_at, updated_at, customer_id, pending_shipping_order.

Example Filters:

Field	Example
status	{ "column": "STATUS", "operator": "EQ", "value": "active" }
customer_id	{ "column": "CUSTOMER_ID", "operator": "EQ", "value": 100001 }
pending_shipping_order	{ "column": "PENDING_SHIPPING_ORDER", "operator": "EXISTS", "value": true }

SubscriptionRuns Filters

The following fields can be used in the where parameter:

id, run_at, status, subscription_id, invoice_id, shipping_order_id, created_at, updated_at.

---

Sorting

Subscriptions Sorting

• id
• label
• status
• next_run_at
• created_at
• updated_at
• customer_id

SubscriptionRuns Sorting

• id
• run_at
• status
• subscription_id
• invoice_id
• shipping_order_id
• created_at
• updated_at

---

Data Types

SubscriptionRun

Field	Type	Description
id	Int	Run ID.
run_at	Date	Date of execution.
status	String	Status of the run (success/error).
error	String	Error message if failed.
subscription	Subscription	Parent subscription.
invoice	Invoice	Generated invoice.
shipping_order	ShippingOrder	Generated shipping order.

SubscriptionRunInvoice

Field	Type	Description
id	Int	Run invoice ID.
company_id	Int	Company ID.
subscription_run_id	Int	Parent run ID.
subscription_customer_id	Int	Customer ID.
status	String	Status (pending, processed, error).
error	String	Error message if failed.
subscription_run	SubscriptionRun	Parent run.
subscription_customer	SubscriptionCustomer	Customer relationship.
invoice	Invoice	Generated invoice.
shipping_order	ShippingOrder	Generated shipping order.

SubscriptionCustomer

Field	Type	Description
id	Int	Subscription customer ID.
company_id	Int	Company ID.
subscription_id	Int	Parent subscription ID.
customer_id	Int	Customer ID.
status	String	Status (active, paused, left).
joined_at	Date	Date customer joined.
left_at	Date	Date customer left.
discount	Float	Customer-specific discount.
discount_type	DiscountType	Discount type (percentage/amount).
customer	Customer	Customer relationship.
subscription	Subscription	Parent subscription.
billing_address	Address	Billing address.
shipping_address	Address	Shipping address.

LineItemSubscription

Field	Type	Description
id	Int	Line item ID.
variant	Variant	Product variant.
location	Location	Stock location.
quantity	Float	Quantity per cycle.
price	Float	Unit price.
subscription	Subscription	Parent subscription.

BatchUpdateSubscriptionLineItemPricesResult

Field	Type	Description
updated_subscriptions_count	Int	Number of subscriptions updated.
updated_line_items_count	Int	Number of line items updated.
queued	Boolean	Whether the update was queued for background processing.
job_batch_id	String	Batch job ID if queued.

---

Data Types

ErplainSubscription

This is the full subscription entity with all available fields.

Field	Type	Description
id	Int	Subscription ID.
label	String	Subscription label.
status	SubscriptionStatus	Current status.
frequency_unit	SubscriptionFrequencyUnit	Frequency unit (day, week, month, year).
frequency_interval	Int	Interval between runs.
billing_period	Int	Billing period length, in days.
max_cycles	Int	Maximum number of cycles.
starts_at	Date	Start date.
ends_at	Date	End date.
next_run_at	Date	Next scheduled execution.
auto_create_shipping_order	Boolean	Create shipment automatically.
invoice_as_draft	Boolean	Create invoice as draft.
currency	Currency	Billing currency.
exchange_rate	Float	Exchange rate for currency conversion.
tax_type	TaxType	Tax calculation method.
default_discount	Float	Default discount rate.
discount_type	DiscountType	Discount type (amount or percentage).
total_units	Float	Total quantity per run.
subtotal	Float	Subtotal per run.
total_without_tax	Float	Total before taxes.
total_ecotax	Float	Total ecotaxes.
total	Float	Grand total per run.
total_taxes	[DocumentTaxRate]	List of taxes applied.
notes	String	Public notes for documents.
internal_notes	String	Private notes.
for_the_attention_of	String	Specific recipient name.
external_reference	String	Merchant internal reference.
invoice_pdf_template	PdfTemplate	Template for invoices.
shipping_order_pdf_template	PdfTemplate	Template for shipping orders.
created_at	DateTime	Creation time.
updated_at	DateTime	Last update time.
hard_deleted_at	DateTime	Hard deletion time.
customer	Customer	Associated customer (deprecated, use customers).
customers	[SubscriptionCustomer]	List of customers.
price_level	PriceLevel	Applied price level.
account_representative	AccountRepresentative	Assigned representative.
season	Season	Associated season.
line_items	[LineItemSubscription]	List of recurring items.
invoices	[Invoice]	Generated invoices.
shipping_orders	[ShippingOrder]	Generated shipping orders.
runs	[SubscriptionRun]	Execution history.

SubscriptionCustomer

Field	Type	Description
id	Int	Customer subscription ID.
customer	Customer	Associated customer.
joined_at	Date	Date customer joined.
left_at	Date	Date customer left.
status	String	Customer status.
billing_address	Address	Billing address.
shipping_address	Address	Shipping address.
discount	Float	Customer-specific discount.
discount_type	DiscountType	Discount type (amount or percentage).

---

Enums

SubscriptionStatus

Value	Description
draft	Not yet active.
active	Running as scheduled.
paused	Temporarily stopped.
cancelled	Permanently stopped.

SubscriptionFrequencyUnit

Value	Description
day	Executes daily.
week	Executes weekly.
month	Executes monthly.
year	Executes yearly.

DiscountType

Value	Description
amount	Fixed discount amount.
percentage	Percentage-based discount.

TaxType

Value	Description
exclusive	Tax calculated on top of the net price.
inclusive	Tax included in the displayed price.