subscriptionBillingCycleCharge

Creates a new subscription billing attempt for a specified billing cycle. This is the alternative mutation for subscriptionBillingAttemptCreate.

Use it in a workflow

Add a step and choose the Shopify connector.
Pick the subscriptionBillingCycleCharge action (under Subscription).
Fill in the fields below, then reference the result from later steps as {{subscriptionbillingcyclecharge.response.data}}.

Query

This is the mutation the action sends by default. Edit it in the step's Query field to change which fields come back.

graphql

mutation SubscriptionBillingCycleCharge($actor: SubscriptionActor, $subscriptionContractId: ID!, $billingCycleSelector: SubscriptionBillingCycleSelector!, $inventoryPolicy: SubscriptionBillingAttemptInventoryPolicy, $paymentProcessingPolicy: SubscriptionBillingAttemptPaymentProcessingPolicy) {
  subscriptionBillingCycleCharge(
    actor: $actor
    subscriptionContractId: $subscriptionContractId
    billingCycleSelector: $billingCycleSelector
    inventoryPolicy: $inventoryPolicy
    paymentProcessingPolicy: $paymentProcessingPolicy
  ) {
    subscriptionBillingAttempt {
      completedAt
      createdAt
      errorCode
      errorMessage
      id
      idempotencyKey
      nextActionUrl
      order {
        additionalFees
        alerts
        app
        attribution
        billingAddress
        billingAddressMatchesShippingAddress
        canMarkAsPaid
        canNotifyCustomer
        cancelReason
        cancellation
        cancelledAt
        capturable
        cartDiscountAmount
        cartDiscountAmountSet
        cartToken
        channel
        channelInformation
        checkoutToken
        clientIp
        closed
        closedAt
        confirmationNumber
        confirmed
        createdAt
        currencyCode
        currentCartDiscountAmountSet
        currentShippingPriceSet
        currentSubtotalLineItemsQuantity
        currentSubtotalPriceSet
        currentTaxLines
        currentTotalAdditionalFeesSet
        currentTotalDiscountsSet
        currentTotalDutiesSet
        currentTotalPriceSet
        currentTotalTaxSet
        currentTotalWeight
        customAttributes
        customer
        customerAcceptsMarketing
        customerJourney
        customerJourneySummary
        customerLocale
        discountCode
        discountCodes
        displayAddress
        displayFinancialStatus
        displayFulfillmentStatus
        disputes
        dutiesIncluded
        edited
        email
        estimatedTaxes
        fulfillable
        fulfillmentsCount
        fullyPaid
        hasTimelineComment
        id
        landingPageDisplayText
        landingPageUrl
        legacyResourceId
        merchantBusinessEntity
        merchantEditable
        merchantEditableErrors
        merchantOfRecordApp
        name
        netPayment
        netPaymentSet
        note
        number
        originalTotalAdditionalFeesSet
        originalTotalDutiesSet
        originalTotalPriceSet
        paymentCollectionDetails
        paymentGatewayNames
        paymentTerms
        phone
        physicalLocation
        poNumber
        presentmentCurrencyCode
        processedAt
        productNetwork
        publication
        purchasingEntity
        referralCode
        referrerDisplayText
        referrerUrl
        refundDiscrepancySet
        refundable
        registeredSourceUrl
        requiresShipping
        restockable
        retailLocation
        returnStatus
        risk
        riskLevel
        shippingAddress
        shippingLine
        shopifyProtect
        sourceIdentifier
        sourceName
        staffMember
        subtotalLineItemsQuantity
        subtotalPrice
        subtotalPriceSet
        tags
        taxExempt
        taxLines
        taxesIncluded
        test
        totalCapturable
        totalCapturableSet
        totalCashRoundingAdjustment
        totalDiscounts
        totalDiscountsSet
        totalOutstandingSet
        totalPrice
        totalPriceSet
        totalReceived
        totalReceivedSet
        totalRefunded
        totalRefundedSet
        totalRefundedShippingSet
        totalShippingPrice
        totalShippingPriceSet
        totalTax
        totalTaxSet
        totalTipReceived
        totalTipReceivedSet
        totalWeight
        transactionsCount
        unpaid
        updatedAt
      }
      originTime
      paymentGroupId
      paymentSessionId
      processingError {
        code
        message
      }
      ready
      respectInventoryPolicy
      state
      subscriptionContract {
        app
        appAdminUrl
        billingPolicy
        createdAt
        currencyCode
        customAttributes
        customer
        deliveryMethod
        deliveryPolicy
        deliveryPrice
        id
        lastBillingAttemptErrorType
        lastPaymentStatus
        lineCount
        linesCount
        nextBillingDate
        note
        originOrder
        revisionId
        status
        updatedAt
      }
    }
    userErrors {
      code
      field
      message
    }
  }
}

Variables

Pass these as a JSON object in the step's Variables field.

actorstring

The actor who initiated a subscription action.

One ofCUSTOMERMERCHANTPARTNER

subscriptionContractIdstringrequired

The ID of the subscription contract.

billingCycleSelectorobjectrequired

Select the specific billing cycle to be billed. If the selected billing cycle's [billingAttemptExpectedDate](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingCycle#field-subscriptionbillingcycle-billingattemptexpecteddate) is in the past, the [originTime](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingAttempt#field-subscriptionbillingattempt-origintime) of the billing attempt will be set to this date. However, if the [billingAttemptExpectedDate](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingCycle#field-subscriptionbillingcycle-billingattemptexpecteddate) is in the future, the originTime will be the current time.

indexnumber

datestring

inventoryPolicystring

The behaviour to use when updating inventory.

One ofPRODUCT_VARIANT_INVENTORY_POLICYALLOW_OVERSELLING

paymentProcessingPolicystring

Select payment processing policy for the billing attempt. Defaults to FAIL_UNLESS_VALID_PAYMENT_METHOD.

One ofFAIL_UNLESS_VALID_PAYMENT_METHODSKIP_PAYMENT_AND_CREATE_UNPAID_ORDER

json

{
  "subscriptionContractId": "string",
  "billingCycleSelector": {
    "index": 0,
    "date": "string"
  },
  "actor": "CUSTOMER",
  "inventoryPolicy": "PRODUCT_VARIANT_INVENTORY_POLICY",
  "paymentProcessingPolicy": "FAIL_UNLESS_VALID_PAYMENT_METHOD"
}

Response

Read the result with {{subscriptionbillingcyclecharge.response.data.data.subscriptionBillingCycleCharge}}. If the API returns errors, the step fails and they are at {{subscriptionbillingcyclecharge.response.data.errors}}.

subscriptionBillingAttemptobject

completedAtstring

createdAtstring

errorCodestring

One ofPAYMENT_METHOD_NOT_FOUNDPAYMENT_PROVIDER_IS_NOT_ENABLEDINVALID_PAYMENT_METHODUNEXPECTED_ERROREXPIRED_PAYMENT_METHODPAYMENT_METHOD_DECLINEDAUTHENTICATION_ERRORTEST_MODEBUYER_CANCELED_PAYMENT_METHODCUSTOMER_NOT_FOUNDCUSTOMER_INVALIDINVALID_SHIPPING_ADDRESSINVALID_CUSTOMER_BILLING_AGREEMENTINVOICE_ALREADY_PAIDPAYMENT_METHOD_INCOMPATIBLE_WITH_GATEWAY_CONFIGAMOUNT_TOO_SMALLAMOUNT_TOO_LARGEMERCHANT_ACCOUNT_ERRORINVENTORY_ALLOCATIONS_NOT_FOUNDINSUFFICIENT_INVENTORYTRANSIENT_ERRORINSUFFICIENT_FUNDSPURCHASE_TYPE_NOT_SUPPORTEDPAYPAL_ERROR_GENERALCARD_NUMBER_INCORRECTFRAUD_SUSPECTEDNON_TEST_ORDER_LIMIT_REACHEDFREE_GIFT_CARD_NOT_ALLOWEDPAYMENT_METHOD_NOT_SPECIFIEDINVALID_BILLING_ADDRESSAUTHENTICATION_FAILEDAUTHENTICATION_REQUIREDCALL_ISSUERCARD_DECLINEDCONFIRMATION_REJECTEDDO_NOT_HONORMERCHANT_RULEOFF_SESSION_REJECTEDRETRY_DECLINEDTRANSACTION_LIMIT_EXCEEDED

errorMessagestring

idstring

idempotencyKeystring

nextActionUrlstring

orderobject40 fields

originTimestring

paymentGroupIdstring

paymentSessionIdstring

processingErrorobject2 fields

readyboolean

respectInventoryPolicyboolean

stateobject4 fields

This field can return one of several different object shapes — properties from every possible shape are shown together.

subscriptionContractobject21 fields

userErrorsarray<object>

codeobject

fieldobject

messageobject

Need more? See the Shopify guide for connection setup and behaviour shared by every action.

Was this page helpful?