Choose a version:

SubscriptionContract

object

Requires the read_own_subscription_contracts or write_own_subscription_contracts scope.

A subscription contract that defines recurring purchases for a customer. Each contract specifies what products to deliver, when to bill and ship them, and at what price.

The contract includes SubscriptionBillingPolicy and SubscriptionDeliveryPolicy that control the frequency of charges and fulfillments. SubscriptionLine items define the products, quantities, and pricing for each recurring Order. The contract tracks SubscriptionBillingAttempt records, payment status, and generated orders throughout its lifecycle. App instances manage contracts through various status transitions including active, paused, failed, cancelled, or expired states.

Learn more about building subscription contracts and updating subscription contracts.

Anchor to FieldsFields

Anchor to appapp

•App

The subscription app that the subscription contract is registered to.

Anchor to appAdminUrlappAdminUrl

•URL

The URL of the subscription contract page on the subscription app.

Anchor to billingAttemptsbillingAttempts

•SubscriptionBillingAttemptConnection!

non-null

The list of billing attempts associated with the subscription contract.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to billingPolicybillingPolicy

•SubscriptionBillingPolicy!

non-null

The billing policy associated with the subscription contract.

Anchor to createdAtcreatedAt

•DateTime!

non-null

The date and time when the subscription contract was created.

Anchor to currencyCodecurrencyCode

•CurrencyCode!

non-null

The currency that's used for the subscription contract.

Anchor to customAttributescustomAttributes

•[Attribute!]!

non-null

A list of the custom attributes to be added to the generated orders.

Anchor to customercustomer

•Customer

The customer to whom the subscription contract belongs.

Anchor to customerPaymentMethodcustomerPaymentMethod

•CustomerPaymentMethod

The customer payment method that's used for the subscription contract.

Anchor to showRevokedshowRevoked •Boolean Default:false: Whether to show the customer's revoked payment method.

Anchor to deliveryMethoddeliveryMethod

•SubscriptionDeliveryMethod

The delivery method for each billing of the subscription contract.

Anchor to deliveryPolicydeliveryPolicy

•SubscriptionDeliveryPolicy!

non-null

The delivery policy associated with the subscription contract.

Anchor to deliveryPricedeliveryPrice

•MoneyV2!

non-null

The delivery price for each billing of the subscription contract.

Anchor to discountsdiscounts

•SubscriptionManualDiscountConnection!

non-null

The list of subscription discounts associated with the subscription contract.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to idid

•ID!

non-null

A globally-unique ID.

Anchor to lastBillingAttemptErrorTypelastBillingAttemptErrorType

•SubscriptionContractLastBillingErrorType

The last billing error type of the contract.

Anchor to lastPaymentStatuslastPaymentStatus

•SubscriptionContractLastPaymentStatus

The current status of the last payment.

Anchor to lineslines

•SubscriptionLineConnection!

non-null

The list of subscription lines associated with the subscription contract.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to linesCountlinesCount

•Count

The number of lines associated with the subscription contract.

Anchor to nextBillingDatenextBillingDate

•DateTime

The next billing date for the subscription contract. This field is managed by the apps. Alternatively you can utilize our Billing Cycles APIs, which provide auto-computed billing dates and additional functionalities.

Anchor to notenote

•String

The note field that will be applied to the generated orders.

Anchor to ordersorders

•OrderConnection!

non-null

A list of the subscription contract's orders.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to originOrderoriginOrder

•Order

The order from which this contract originated.

Anchor to revisionIdrevisionId

•UnsignedInt64!

non-null

The revision id of the contract.

Anchor to statusstatus

•SubscriptionContractSubscriptionStatus!

non-null

The current status of the subscription contract.

Anchor to updatedAtupdatedAt

•DateTime!

non-null

The date and time when the subscription contract was updated.

Anchor to lineCountlineCount

•Int!

non-nullDeprecated

Was this section helpful?

Anchor to QueriesQueries

Anchor to subscriptionContract subscriptionContract

•query

Retrieves a SubscriptionContract by ID.

The contract tracks the subscription's lifecycle through various statuses, and links to related billing attempts, generated Order objects, and the customer's CustomerPaymentMethod.

Anchor to idid •ID! required: The ID of the Subscription Contract to return.

Anchor to subscriptionContracts subscriptionContracts

•query

Returns a SubscriptionContractConnection containing subscription contracts. Subscription contracts are agreements between customers and merchants for recurring purchases with defined billing and delivery schedules.

Filter results with the query argument. You can paginate results using standard cursor-based pagination.

Arguments

Anchor to firstfirst

•Int

The first n elements from the paginated list.

Anchor to afterafter

•String

The elements that come after the specified cursor.

Anchor to lastlast

•Int

The last n elements from the paginated list.

Anchor to beforebefore

•String

The elements that come before the specified cursor.

Anchor to reversereverse

•Boolean

Default:false

Reverse the order of the underlying list.

Anchor to sortKeysortKey

•SubscriptionContractsSortKeys

Default:CREATED_AT

Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.

Anchor to queryquery

•String

A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about Shopify API search syntax.

Anchor to created_at •time
Anchor to id •id: Filter by id range.
Anchor to last_billing_attempt_error_type •string
Anchor to status •string
Anchor to updated_at •time

Was this section helpful?

Anchor to MutationsMutations

Anchor to subscriptionContractActivate subscriptionContractActivate

•mutation

Activates a Subscription Contract. Contract status must be either active, paused, or failed.

Anchor to subscriptionContractIdsubscriptionContractId •ID! required: The ID of the Subscription Contract.

Anchor to subscriptionContractAtomicCreate subscriptionContractAtomicCreate

•mutation

Creates a Subscription Contract.

Arguments

Anchor to inputinput

•SubscriptionContractAtomicCreateInput!

required

The properties of the new Subscription Contract.

Anchor to subscriptionContractCancel subscriptionContractCancel

•mutation

Cancels a Subscription Contract.

Anchor to subscriptionContractIdsubscriptionContractId •ID! required: The ID of the Subscription Contract.

Anchor to subscriptionContractExpire subscriptionContractExpire

•mutation

Expires a Subscription Contract.

Anchor to subscriptionContractIdsubscriptionContractId •ID! required: The ID of the Subscription Contract.

Anchor to subscriptionContractFail subscriptionContractFail

•mutation

Fails a Subscription Contract.

Anchor to subscriptionContractIdsubscriptionContractId •ID! required: The ID of the Subscription Contract.

Anchor to subscriptionContractPause subscriptionContractPause

•mutation

Pauses a Subscription Contract.

Anchor to subscriptionContractIdsubscriptionContractId •ID! required: The ID of the Subscription Contract.

Anchor to subscriptionContractProductChange subscriptionContractProductChange

•mutation

Allows for the easy change of a Product in a Contract or a Product price change.

Arguments

Anchor to subscriptionContractIdsubscriptionContractId

•ID!

required

The ID of the subscription contract.

Anchor to lineIdlineId

•ID!

required

The gid of the Subscription Line to update.

Anchor to inputinput

•SubscriptionContractProductChangeInput!

required

The properties of the Product changes.

Anchor to subscriptionContractSetNextBillingDate subscriptionContractSetNextBillingDate

•mutation

Sets the next billing date of a Subscription Contract. This field is managed by the apps. Alternatively you can utilize our Billing Cycles APIs, which provide auto-computed billing dates and additional functionalities.

Anchor to contractIdcontractId •ID! required: The gid of the Subscription Contract to set the next billing date for.
Anchor to datedate •DateTime! required: The next billing date.

Anchor to subscriptionDraftCommit subscriptionDraftCommit

•mutation

Commits the updates of a Subscription Contract draft.

Anchor to draftIddraftId •ID! required: The gid of the Subscription Contract draft to commit.

Was this section helpful?

Anchor to InterfacesInterfaces

Anchor to Node Node •interface
Anchor to SubscriptionContractBase SubscriptionContractBase •interface

Was this section helpful?