--- title: SubscriptionContract - GraphQL Admin description: >- 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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingPolicy) and [`SubscriptionDeliveryPolicy`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionDeliveryPolicy) that control the frequency of charges and fulfillments. [`SubscriptionLine`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionLine) items define the products, quantities, and pricing for each recurring [`Order`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order). The contract tracks [`SubscriptionBillingAttempt`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingAttempt) records, payment status, and generated orders throughout its lifecycle. [`App`](https://shopify.dev/docs/api/admin-graphql/latest/objects/App) instances manage contracts through various status transitions including active, paused, failed, cancelled, or expired states. Learn more about [building subscription contracts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract) and [updating subscription contracts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract). api_version: unstable api_name: admin source_url: html: >- https://shopify.dev/docs/api/admin-graphql/unstable/objects/SubscriptionContract md: >- https://shopify.dev/docs/api/admin-graphql/unstable/objects/SubscriptionContract.md --- # Subscription​Contract 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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingPolicy) and [`SubscriptionDeliveryPolicy`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionDeliveryPolicy) that control the frequency of charges and fulfillments. [`SubscriptionLine`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionLine) items define the products, quantities, and pricing for each recurring [`Order`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order). The contract tracks [`SubscriptionBillingAttempt`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingAttempt) records, payment status, and generated orders throughout its lifecycle. [`App`](https://shopify.dev/docs/api/admin-graphql/latest/objects/App) instances manage contracts through various status transitions including active, paused, failed, cancelled, or expired states. Learn more about [building subscription contracts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract) and [updating subscription contracts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract). ## Fields * app [App](https://shopify.dev/docs/api/admin-graphql/unstable/objects/App) The subscription app that the subscription contract is registered to. * app​Admin​Url [URL](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/URL) The URL of the subscription contract page on the subscription app. * billing​Attempts [Subscription​Billing​Attempt​Connection!](https://shopify.dev/docs/api/admin-graphql/unstable/connections/SubscriptionBillingAttemptConnection) non-null The list of billing attempts associated with the subscription contract. * first [Int](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * billing​Policy [Subscription​Billing​Policy!](https://shopify.dev/docs/api/admin-graphql/unstable/objects/SubscriptionBillingPolicy) non-null The billing policy associated with the subscription contract. * created​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/DateTime) non-null The date and time when the subscription contract was created. * currency​Code [Currency​Code!](https://shopify.dev/docs/api/admin-graphql/unstable/enums/CurrencyCode) non-null The currency that's used for the subscription contract. * custom​Attributes [\[Attribute!\]!](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Attribute) non-null A list of the custom attributes to be added to the generated orders. * customer [Customer](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Customer) The customer to whom the subscription contract belongs. * customer​Payment​Method [Customer​Payment​Method](https://shopify.dev/docs/api/admin-graphql/unstable/objects/CustomerPaymentMethod) The customer payment method that's used for the subscription contract. * show​Revoked [Boolean](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Boolean) Default:false ### Arguments Whether to show the customer's revoked payment method. *** * delivery​Method [Subscription​Delivery​Method](https://shopify.dev/docs/api/admin-graphql/unstable/unions/SubscriptionDeliveryMethod) The delivery method for each billing of the subscription contract. * delivery​Policy [Subscription​Delivery​Policy!](https://shopify.dev/docs/api/admin-graphql/unstable/objects/SubscriptionDeliveryPolicy) non-null The delivery policy associated with the subscription contract. * delivery​Price [Money​V2!](https://shopify.dev/docs/api/admin-graphql/unstable/objects/MoneyV2) non-null The delivery price for each billing of the subscription contract. * discounts [Subscription​Manual​Discount​Connection!](https://shopify.dev/docs/api/admin-graphql/unstable/connections/SubscriptionManualDiscountConnection) non-null The list of subscription discounts associated with the subscription contract. * first [Int](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) non-null A globally-unique ID. * last​Billing​Attempt​Error​Type [Subscription​Contract​Last​Billing​Error​Type](https://shopify.dev/docs/api/admin-graphql/unstable/enums/SubscriptionContractLastBillingErrorType) The last billing error type of the contract. * last​Payment​Status [Subscription​Contract​Last​Payment​Status](https://shopify.dev/docs/api/admin-graphql/unstable/enums/SubscriptionContractLastPaymentStatus) The current status of the last payment. * lines [Subscription​Line​Connection!](https://shopify.dev/docs/api/admin-graphql/unstable/connections/SubscriptionLineConnection) non-null The list of subscription lines associated with the subscription contract. * first [Int](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * lines​Count [Count](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Count) The number of lines associated with the subscription contract. * next​Billing​Date [Date​Time](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/DateTime) The next billing date for the subscription contract. This field is managed by the apps. Alternatively you can utilize our [Billing Cycles APIs](https://shopify.dev/docs/apps/selling-strategies/subscriptions/billing-cycles), which provide auto-computed billing dates and additional functionalities. * note [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The note field that will be applied to the generated orders. * orders [Order​Connection!](https://shopify.dev/docs/api/admin-graphql/unstable/connections/OrderConnection) non-null A list of the subscription contract's orders. * first [Int](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * origin​Order [Order](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Order) The order from which this contract originated. * revision​Id [Unsigned​Int64!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/UnsignedInt64) non-null The revision id of the contract. * status [Subscription​Contract​Subscription​Status!](https://shopify.dev/docs/api/admin-graphql/unstable/enums/SubscriptionContractSubscriptionStatus) non-null The current status of the subscription contract. * updated​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/DateTime) non-null The date and time when the subscription contract was updated. * line​Count [Int!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) non-nullDeprecated *** ## Map ### Fields and connections with this object * {}[Customer.subscriptionContracts](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Customer#field-Customer.fields.subscriptionContracts) * {}[CustomerPaymentMethod.subscriptionContracts](https://shopify.dev/docs/api/admin-graphql/unstable/objects/CustomerPaymentMethod#field-CustomerPaymentMethod.fields.subscriptionContracts) * {}[LineItem.contract](https://shopify.dev/docs/api/admin-graphql/unstable/objects/LineItem#field-LineItem.fields.contract) * {}[SubscriptionBillingAttempt.subscriptionContract](https://shopify.dev/docs/api/admin-graphql/unstable/objects/SubscriptionBillingAttempt#field-SubscriptionBillingAttempt.fields.subscriptionContract) * {}[SubscriptionBillingCycle.sourceContract](https://shopify.dev/docs/api/admin-graphql/unstable/objects/SubscriptionBillingCycle#field-SubscriptionBillingCycle.fields.sourceContract) * <->[SubscriptionContractConnection.nodes](https://shopify.dev/docs/api/admin-graphql/unstable/connections/SubscriptionContractConnection#returns-nodes) * {}[SubscriptionContractEdge.node](https://shopify.dev/docs/api/admin-graphql/unstable/objects/SubscriptionContractEdge#field-SubscriptionContractEdge.fields.node) * {}[SubscriptionDraft.originalContract](https://shopify.dev/docs/api/admin-graphql/unstable/objects/SubscriptionDraft#field-SubscriptionDraft.fields.originalContract) * {}[SubscriptionLine.concatenatedOriginContract](https://shopify.dev/docs/api/admin-graphql/unstable/objects/SubscriptionLine#field-SubscriptionLine.fields.concatenatedOriginContract) *** ## Queries * [subscription​Contract](https://shopify.dev/docs/api/admin-graphql/unstable/queries/subscriptionContract) query Retrieves a [`SubscriptionContract`](https://shopify.dev/docs/api/customer/latest/objects/SubscriptionContract) by ID. The contract tracks the subscription's lifecycle through various [statuses](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptionContract#returns-SubscriptionContract.fields.status), and links to related billing attempts, generated [`Order`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) objects, and the customer's [`CustomerPaymentMethod`](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerPaymentMethod). * id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) required ### Arguments The ID of the Subscription Contract to return. *** * [subscription​Contracts](https://shopify.dev/docs/api/admin-graphql/unstable/queries/subscriptionContracts) query Returns a [`SubscriptionContractConnection`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionContractConnection) containing [subscription contracts](https://shopify.dev/docs/api/customer/latest/objects/SubscriptionContract). Subscription contracts are agreements between [customers](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer) and merchants for recurring purchases with defined billing and delivery schedules. Filter results with the [`query`](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptionContracts#arguments-query) argument. You can paginate results using standard [cursor-based pagination](https://shopify.dev/docs/api/usage/pagination-graphql). * first [Int](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Subscription​Contracts​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/unstable/enums/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](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). * query [String](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/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](https://shopify.dev/api/usage/search-syntax). * created\_at time * * id id * last\_billing\_attempt\_error\_type string - Filter by `id` range. - Example: * `id:1234` * `id:>=1234` * `id:<=1234` * status string * updated\_at time *** *** ## \SubscriptionContract Queries ### Queried by * \[subscription​Contract](https://shopify.dev/docs/api/admin-graphql/unstable/queries/subscriptionContract) * \[subscription​Contracts](https://shopify.dev/docs/api/admin-graphql/unstable/queries/subscriptionContracts) *** ## Mutations * [subscription​Contract​Activate](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractActivate) mutation Activates a Subscription Contract. Contract status must be either active, paused, or failed. * subscription​Contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) required ### Arguments The ID of the Subscription Contract. *** * [subscription​Contract​Atomic​Create](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractAtomicCreate) mutation Creates a Subscription Contract. * input [Subscription​Contract​Atomic​Create​Input!](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/SubscriptionContractAtomicCreateInput) required ### Arguments The properties of the new Subscription Contract. *** * [subscription​Contract​Cancel](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractCancel) mutation Cancels a Subscription Contract. * subscription​Contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) required ### Arguments The ID of the Subscription Contract. *** * [subscription​Contract​Expire](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractExpire) mutation Expires a Subscription Contract. * subscription​Contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) required ### Arguments The ID of the Subscription Contract. *** * [subscription​Contract​Fail](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractFail) mutation Fails a Subscription Contract. * subscription​Contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) required ### Arguments The ID of the Subscription Contract. *** * [subscription​Contract​Pause](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractPause) mutation Pauses a Subscription Contract. * subscription​Contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) required ### Arguments The ID of the Subscription Contract. *** * [subscription​Contract​Product​Change](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractProductChange) mutation Allows for the easy change of a Product in a Contract or a Product price change. * subscription​Contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) required ### Arguments The ID of the subscription contract. * line​Id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) required The gid of the Subscription Line to update. * input [Subscription​Contract​Product​Change​Input!](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/SubscriptionContractProductChangeInput) required The properties of the Product changes. *** * [subscription​Contract​Set​Next​Billing​Date](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/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](https://shopify.dev/docs/apps/selling-strategies/subscriptions/billing-cycles), which provide auto-computed billing dates and additional functionalities. * contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) required ### Arguments The gid of the Subscription Contract to set the next billing date for. * date [Date​Time!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/DateTime) required The next billing date. *** * [subscription​Draft​Commit](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionDraftCommit) mutation Commits the updates of a Subscription Contract draft. * draft​Id [ID!](https://shopify.dev/docs/api/admin-graphql/unstable/scalars/ID) required ### Arguments The gid of the Subscription Contract draft to commit. *** *** ## <\~> SubscriptionContract Mutations ### Mutated by * <\~>[subscription​Contract​Activate](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractActivate) * <\~>[subscription​Contract​Atomic​Create](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractAtomicCreate) * <\~>[subscription​Contract​Cancel](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractCancel) * <\~>[subscription​Contract​Expire](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractExpire) * <\~>[subscription​Contract​Fail](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractFail) * <\~>[subscription​Contract​Pause](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractPause) * <\~>[subscription​Contract​Product​Change](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractProductChange) * <\~>[subscription​Contract​Set​Next​Billing​Date](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionContractSetNextBillingDate) * <\~>[subscription​Draft​Commit](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptionDraftCommit) *** ## Interfaces * * [Node](https://shopify.dev/docs/api/admin-graphql/unstable/interfaces/Node) interface * [Subscription​Contract​Base](https://shopify.dev/docs/api/admin-graphql/unstable/interfaces/SubscriptionContractBase) interface *** ## ||-SubscriptionContract Implements ### Implements * ||-[Node](https://shopify.dev/docs/api/admin-graphql/unstable/interfaces/Node) * ||-[Subscription​Contract​Base](https://shopify.dev/docs/api/admin-graphql/unstable/interfaces/SubscriptionContractBase)