Subscriptions Mutations

CreateSubscription

Creates a new recurring subscription.

Parameters:

Parameter	Type	Description
input	SubscriptionInput!	Subscription data.

Example Query:

GraphQL

mutation CreateSubscription($input: SubscriptionInput!) {
  CreateSubscription(input: $input) {
    id
    label
    status
  }
}

---

UpdateSubscription

Updates an existing recurring subscription.

Parameters:

Parameter	Type	Description
id	Int!	ID of the subscription.
input	SubscriptionInput!	Updated data.

---

BulkCreateSubscriptions

Creates multiple subscriptions from a template for several customers.

Parameters:

Parameter	Type	Description
input	BulkCreateSubscriptionsInput!	Bulk creation settings.

---

DeleteSubscription / DeleteSubscriptions

Deletes one or multiple subscriptions.

---

GenerateSubscriptionDocuments

Manually triggers the generation of documents for a subscription cycle on a specific date.

Parameters:

Parameter	Type	Description
subscription_id	Int!	Parent ID.
run_at	Date	Execution date.
published	Boolean	Whether to publish generated documents.

---

BatchUpdateSubscriptionLineItemPrices

Updates prices for recurring items across multiple subscriptions based on specific rules.

---

CreatePendingSubscriptionShippingOrder

Creates a pending shipping order for a subscription run invoice.

Parameters:

Parameter	Type	Description
run_invoice_id	ID!	ID of the subscription run invoice.

Example Query:

GraphQL

mutation CreatePendingSubscriptionShippingOrder($run_invoice_id: ID!) {
  CreatePendingSubscriptionShippingOrder(run_invoice_id: $run_invoice_id) {
    id
    status
    shipping_order {
      id
      label
    }
  }
}

Return Type	Description
SubscriptionRunInvoice	The subscription run invoice with created shipping order.

---

AddCustomerToSubscription

Adds a customer to an existing subscription.

Parameters:

Parameter	Type	Description
subscription_id	ID!	ID of the subscription.
input	AddSubscriptionCustomerInput!	Customer data.

Example Query:

GraphQL

mutation AddCustomerToSubscription($subscription_id: ID!, $input: AddSubscriptionCustomerInput!) {
  AddCustomerToSubscription(subscription_id: $subscription_id, input: $input) {
    id
    customer {
      id
      label
    }
    status
  }
}

Return Type	Description
SubscriptionCustomer	The added customer relationship.

---

RemoveCustomerFromSubscription

Removes a customer from a subscription.

Parameters:

Parameter	Type	Description
subscription_id	ID!	ID of the subscription.
subscription_customer_id	ID!	ID of the subscription customer to remove.

Example Query:

GraphQL

mutation RemoveCustomerFromSubscription($subscription_id: ID!, $subscription_customer_id: ID!) {
  RemoveCustomerFromSubscription(subscription_id: $subscription_id, subscription_customer_id: $subscription_customer_id)
}

Return Type	Description
Boolean	true if successful.

---

PauseCustomerOnSubscription

Pauses a customer's participation in a subscription.

Parameters:

Parameter	Type	Description
subscription_id	ID!	ID of the subscription.
subscription_customer_id	ID!	ID of the subscription customer to pause.

Example Query:

GraphQL

mutation PauseCustomerOnSubscription($subscription_id: ID!, $subscription_customer_id: ID!) {
  PauseCustomerOnSubscription(subscription_id: $subscription_id, subscription_customer_id: $subscription_customer_id)
}

Return Type	Description
Boolean	true if successful.

---

ReactivateCustomerOnSubscription

Reactivates a previously paused customer on a subscription.

Parameters:

Parameter	Type	Description
subscription_id	ID!	ID of the subscription.
subscription_customer_id	ID!	ID of the subscription customer to reactivate.

Example Query:

GraphQL

mutation ReactivateCustomerOnSubscription($subscription_id: ID!, $subscription_customer_id: ID!) {
  ReactivateCustomerOnSubscription(subscription_id: $subscription_id, subscription_customer_id: $subscription_customer_id)
}

Return Type	Description
Boolean	true if successful.

---

UpdateSubscriptionCustomer

Updates a customer's settings on a subscription.

Parameters:

Parameter	Type	Description
subscription_id	ID!	ID of the subscription.
input	UpdateSubscriptionCustomerInput!	Updated customer data.

Example Query:

GraphQL

mutation UpdateSubscriptionCustomer($subscription_id: ID!, $input: UpdateSubscriptionCustomerInput!) {
  UpdateSubscriptionCustomer(subscription_id: $subscription_id, input: $input) {
    id
    customer {
      id
      label
    }
    discount
    discount_type
  }
}

Return Type	Description
SubscriptionCustomer	The updated customer relationship.

---

RetrySubscriptionRunInvoice

Retries processing a failed subscription run invoice.

Parameters:

Parameter	Type	Description
id	ID!	ID of the subscription run invoice.
published	Boolean	Whether to publish the generated document.

Example Query:

GraphQL

mutation RetrySubscriptionRunInvoice($id: ID!, $published: Boolean) {
  RetrySubscriptionRunInvoice(id: $id, published: $published) {
    id
    status
    invoice {
      id
      label
    }
  }
}

Return Type	Description
SubscriptionRunInvoice	The retried subscription run invoice.

---

GenerateSubscriptionNumber

Generates a unique number for a new subscription.

Parameters:

Parameter	Type	Description
location_id	ID	Optional location ID for the number format.

Example Query:

GraphQL

mutation GenerateSubscriptionNumber($location_id: ID) {
  GenerateSubscriptionNumber(location_id: $location_id)
}

Return Type	Description
String	Generated subscription number.

---

Input Data Types

SubscriptionInput

Field	Type	Description
id	Int	ID for updates.
label	String	Subscription reference number.
status	SubscriptionStatus	Initial or updated status.
frequency_unit	SubscriptionFrequencyUnit	Frequency unit (day, week, month, year).
frequency_interval	Int	Number of units between executions.
max_cycles	Int	Limit of runs before termination.
starts_at	Date	Start date.
ends_at	Date	End date.
next_run_at	Date	Override next run date.
auto_create_shipping_order	Boolean	Automate shipment creation.
invoice_as_draft	Boolean	Automate invoice as draft.
currency	CurrencyInput	Billing currency.
exchange_rate	Float	Exchange rate.
tax_type	TaxType	Tax calculation method.
default_discount	Float	Default discount rate.
discount_type	DiscountType	Discount type.
notes	String	Public notes.
internal_notes	String	Private notes.
for_the_attention_of	String	Recipient name.
external_reference	String	Merchant reference.
customer	CustomerInput	Linked customer.
price_level	PriceLevelInput	Price level override.
account_representative	AccountRepresentativeInput	Responsible agent.
season	SeasonInput	Linked season.
invoice_pdf_template	PdfTemplateInput	Invoice design.
shipping_order_pdf_template	PdfTemplateInput	Shipping order design.
billing_address	AddressInput	Billing address.
shipping_address	AddressInput	Shipping address.
line_items	[LineItemSubscriptionInput]	Recurring items.
custom_fields	[EntityCustomFieldInput]	Custom fields for this entity.
customers	[SubscriptionCustomerInput]	List of customers.

---

LineItemSubscriptionInput

Field	Type	Description
id	ID	Line item ID (for updates).
location_id	String	Location ID.
location	LocationInput	Location details.
variant_id	String	Variant ID.
variant	VariantInput	Variant details.
quantity	Float	Quantity.
price	Float	Unit price.
calculate_price_from_components	Boolean	Calculate price from components.
drop_shipping	Int	Drop shipping flag.
parent_id	Int	Parent line item ID (for kits).
weight	Int	Weight.
description	String	Line item description.
replace_label	Boolean	Replace label with description.
discount_type	DiscountType	Discount type (amount, percentage).
discount	Float	Discount value.
discount_rule_id	ID	Applied discount rule ID.
discount_rule_amount	Float	Discount rule amount.
tax_amount	Float	Tax amount.
ecotax	Float	Ecotax amount.
tax_codes	[TaxCodeInput]	Tax codes.
temporary_id	ID	Temporary ID for kits & packaging.
kit_line_item_id	ID	Kit line item ID.
type	String	Line item type.
batch_numbers	[BatchNumberLineItemInput]	Batch numbers.

SubscriptionCustomerInput

Field	Type	Description
id	ID	Customer subscription ID (for updates).
customer	CustomerInput!	Customer data (required).
joined_at	Date	Date customer joined.
left_at	Date	Date customer left.
billing_address	AddressInput	Billing address.
shipping_address	AddressInput	Shipping address.
discount	Float	Customer-specific discount.
discount_type	DiscountType	Discount type (amount or percentage).
status	String	Customer status.

---

BulkCreateSubscriptionsInput

Field	Type	Description
customer_ids	[Int!]	IDs of target customers.
template	SubscriptionInput!	Base configuration template.
pricing_mode	SubscriptionBulkPricingMode!	How to calculate prices for each customer.
use_customer_discount	Boolean	Apply individual customer discounts.
use_customer_addresses	Boolean	Use each customer's default addresses.
use_customer_account_representative	Boolean	Use customer-assigned representatives.
use_customer_location	Boolean	Use customer-assigned stock locations.
use_customer_price_level	Boolean	Use customer-assigned price levels.
use_customer_currency	Boolean	Use customer-assigned currencies.

---

BatchUpdateSubscriptionLineItemPricesInput

Field	Type	Description
subscription_ids	[Int]	Specific subscriptions to update.
rules	[SubscriptionPriceRuleInput!]	Pricing update rules.

---

SubscriptionPriceRuleInput

Field	Type	Description
variant_id	Int!	ID of the product variant.
price	Float	Explicit price (for fixed mode).
mode	SubscriptionPriceRuleMode!	Update strategy.
value	Float	Value for increase or fixed modes.

---

AddSubscriptionCustomerInput

Field	Type	Description
customer	CustomerInput!	Customer to add.
joined_at	Date	Date customer joined.
prorata_mode	AddSubscriptionCustomerProrataMode	Prorata calculation mode.
published	Boolean	Whether the customer is active.
billing_address	AddressInput	Billing address.
shipping_address	AddressInput	Shipping address.
discount	Float	Customer-specific discount.
discount_type	DiscountType	Discount type (percentage/amount).
status	String	Initial status.

---

UpdateSubscriptionCustomerInput

Field	Type	Description
id	ID	Subscription customer ID.
customer	CustomerInput	Updated customer reference.
joined_at	Date	Date customer joined.
left_at	Date	Date customer left.
billing_address	AddressInput	Billing address.
shipping_address	AddressInput	Shipping address.
discount	Float	Customer-specific discount.
discount_type	DiscountType	Discount type (percentage/amount).
status	String	Customer status.

---

Enums

SubscriptionStatus

Value	Description
draft	Not yet active.
active	Active and generating documents.
paused	Temporarily stopped.
cancelled	Permanently terminated.

SubscriptionFrequencyUnit

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

SubscriptionBulkPricingMode

Value	Description
fixed_prices	Use prices specified in the template.
customer_price_level	Calculate prices based on customer's level.

SubscriptionPriceRuleMode

Value	Description
fixed	Sets the price to a specific value.
increase_amount	Increases the current price by a fixed amount.
increase_percentage	Increases the current price by a percentage.

AddSubscriptionCustomerProrataMode

Value	Description
prorata_now	Calculate prorata immediately based on remaining time in the current cycle.
wait_next_run	Wait until the next scheduled run to include the customer.

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.