Admin GraphQL API / 2026-04 RC

From a subscription billing attempt,
you can now create an "unpaid order"

subscriptionBillingAttemptCreate now has a new field paymentProcessingPolicy added. Even without a valid payment method, you now have the option to create an order in an unpaid state.

On this page
  1. What's actually changing (understand in 30 seconds)
  2. The two values of paymentProcessingPolicy
  3. How it works: from billing attempt to order
  4. Comparing the two behaviors
  5. Prerequisites and notes (version and scope)
  6. 5 points engineers should know
  7. 3 use cases you can apply to your business
  8. One-line summary for proposals

1What's actually changing

When creating a subscription billing attempt (billing attempt = the action of charging a customer based on a contract),
you can now create an "unpaid order" even if the payment method is invalid—a new option has been added.
The new field that switches this behavior is paymentProcessingPolicy.

Before: a valid payment method was required

To complete an order via a billing attempt, the contract had to have a valid payment method. Without one, no order could be created.

UNPAID

From now on: orders can also be created in an unpaid state

paymentProcessingPolicy in SKIP_PAYMENT_AND_CREATE_UNPAID_ORDER specifying this creates an unpaid order even without a valid payment method.

2The two values of paymentProcessingPolicy

Default / when omitted

FAIL_UNLESS_VALID_PAYMENT_METHOD

Behavior is the same whether you omit the field or explicitly specify this value.Order creation fails if there's no valid payment method(= same as the previous behavior).

New option

SKIP_PAYMENT_AND_CREATE_UNPAID_ORDER

Even if the subscription contract has no valid payment method,the system creates an unpaid order. Think of it as skipping payment processing and just creating the order first.

Not passing the field = legacy behavior. In other words, existing subscriptionBillingAttemptCreate calls will continue to work as before if you do nothing (backward compatible).

3How it works: from billing attempt to order creation

Subscription contract subscription contract subscriptionBilling AttemptCreate + paymentProcessingPolicy Payment method Is it valid? Valid → create a regular order (payment processing runs) Invalid → unpaid order SKIP_PAYMENT_AND_ When CREATE_UNPAID_ORDER is specified
Legacy behavior (default / FAIL_UNLESS_VALID_PAYMENT_METHOD) fails to create an order if the payment method is invaliddoes not succeed. Specify it explicitly only when you want to create an unpaid order SKIP_PAYMENT_AND_CREATE_UNPAID_ORDER explicitly.

4Comparison of the two behaviors

ItemFAIL_UNLESS_VALID_PAYMENT_METHOD (default / when omitted)SKIP_PAYMENT_AND_CREATE_UNPAID_ORDER
Is a valid payment method required? Required Order creation fails without one Not required Order is created even without one
Order created Regular order (with payment processing) Unpaid order (skips payment)
Behavior when the field is omitted Same as this —
Backward compatibility Same as before New behavior requiring explicit specification

5Prerequisites and notes (version and scope)

2026-04 RC

API 2026-04 release candidate

This feature 2026-04 release candidate became available in. The article does not state when it will be in the stable release or when the spec will be finalizednot stated.

See the docs for implementation details

For concrete implementation steps, the article points to the "building a subscription contract" documentation. Check that for API schema details and error behavior.

The target is Admin GraphQL API 's subscriptionBillingAttemptCreate mutation. The article does not detail the downstream flow for unpaid orders (invoice issuance, payment reconciliation, dunning, etc.).

65 key points for engineers

FIELD

1. The addition is a single input field

subscriptionBillingAttemptCreate to paymentProcessingPolicy Just pass it in. The diff is just adding one field to your existing billing attempt flow.

2. Omitting it preserves the previous behavior (backward compatible)

When unspecified, it behaves the same as FAIL_UNLESS_VALID_PAYMENT_METHOD . Existing code keeps working as-is if you don't touch it.

UNPAID

3. Unpaid orders "skip payment"

SKIP_PAYMENT_AND_CREATE_UNPAID_ORDER creates an order without running payment processing. The design assumes that collecting payment is handled in a separate flow after order creation.

4. Branching is determined by the validity of the payment method

Behavior depends on "whether the contract has a valid payment method." Flows aimed at creating unpaid orders should be implemented with awareness of the payment method state on the contract side.

RC

5. It's a 2026-04 RC, so pin and verify before going to production

A feature now available in the release candidate. For production use, pin the API version to 2026-04 and verify unpaid order generation and downstream processing in a sandbox before shipping. Follow the "building a subscription contract" doc for implementation details.

7Three use cases you can apply to your business

UNPAID
USE CASE 1

"Invoice payment (deferred billing)" operations for B2B subscriptions

Challenge
For B2B recurring purchases, you want to collect later via invoice or bank transfer rather than charging a card each time. Previously, you couldn't create an order without a valid payment method, so you couldn't put it on the subscription's automatic billing cycle.
Solution
At billing time, specify SKIP_PAYMENT_AND_CREATE_UNPAID_ORDER to create the order as an unpaid order. Billing and collection are handled separately offline.
Result
Customers with payment terms other than card can be put on subscription billing cycles, and order creation can be automated.
Technical note
subscriptionBillingAttemptCreate Just switch the policy at runtime. Payment reconciliation is handled by your own/external flow after order creation.
retry
USE CASE 2

Dunning design that "creates the order first" when payment fails

Challenge
When a charge fails due to an expired card, etc., the order itself wouldn't be created previously, which broke the correspondence between contracts and orders and made dunning and retry management complicated.
Solution
Create an unpaid order for cycles where the payment method is invalid, then switch to an operation where you collect and reconcile after the payment method is updated.
Result
Orders for each cycle are recorded without omission, making it easier to track unpaid receivables and set up dunning flows.
Technical note
Since the default (when the field is omitted) is to fail, implement branching that explicitly passes SKIP_PAYMENT_AND_CREATE_UNPAID_ORDER only for dunning targets.
Order External
USE CASE 3

Creating recurring orders that integrate with external payment / in-house billing systems

Challenge
You want payment to be handled by an external system or your own credit flow, with only the order fact recorded on the Shopify side, but you couldn't create an order without giving Shopify a valid payment method.
Solution
Create unpaid orders on billing attempts and process the payment itself externally. Shopify serves as the source of truth for orders and contracts.
Impact
You can separate the payment layer from the order management layer, putting Shopify Subscriptions on top while continuing to leverage your existing credit/payment assets.
Technical notes
Follow the "building a subscription contract" doc for implementation. The downstream flow for unpaid orders (syncing payment status) needs to be designed separately.

8One-line summary for proposals

"Subscription billing attempts now support paymentProcessingPolicy . Specifying
SKIP_PAYMENT_AND_CREATE_UNPAID_ORDER lets you create an 'unpaid order' even without a valid payment method.
When omitted, behavior is unchanged (a valid payment method is required) — backward compatible. Useful for filing deferred payments, dunning, and external payment integrations (2026-04 RC)."