Split or duplicate an existing subscription contract

Creates a new subscription contract by either splitting (moving) or duplicating selected line items from an existing contract. This endpoint allows you to divide a subscription into multiple contracts or create a copy with specific products.

Full behavior, validation rules, and side effects

Split vs Duplicate Mode:

• Split (isSplitContract=true): Moves the selected line items from the original contract to a new contract. The original contract will no longer contain these items.
• Duplicate (isSplitContract=false): Creates a new contract with copies of the selected line items while keeping them in the original contract.

Important Notes:

• When splitting, at least one subscription product must remain in the original contract
• The new contract inherits all settings from the original: customer, payment method, billing/delivery policies, shipping address, and custom attributes
• Billing schedule is automatically generated for the new contract
• One-time products and free products don’t count towards the minimum product requirement

Use Cases:

• Split a subscription when customer wants different delivery schedules for different products
• Create a gift subscription from an existing subscription
• Separate products for different shipping addresses
• Duplicate a subscription for testing or backup purposes

Authentication: Requires valid X-API-Key header

POST /subscriptions/cp/api/subscription-contract-details/split-existing-contract

Split or duplicate an existing subscription contract

cURL

curl --request POST \
  --url https://www.myshop.com/apps/subscriptions/cp/api/subscription-contract-details/split-existing-contract \
  --header 'Content-Type: application/json' \
  --data '[
  "<string>"
]'

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/987654321",
  "status": "ACTIVE",
  "nextBillingDate": "2024-02-15T00:00:00Z",
  "originOrder": {
    "id": "gid://shopify/Order/123456789"
  },
  "customer": {
    "id": "gid://shopify/Customer/111111",
    "email": "[e-mail]"
  },
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/222222",
          "quantity": 2,
          "variantId": "gid://shopify/ProductVariant/333333",
          "title": "Premium Coffee - Medium Roast",
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          }
        }
      }
    ]
  },
  "customAttributes": [
    {
      "key": "_origin_type",
      "value": "SPLIT_CONTRACT"
    },
    {
      "key": "_original_contract_id",
      "value": "123456789"
    }
  ]
}

Query Parameters

contractId · integer<int64> · required

isSplitContract · boolean · default: false

attemptBilling · boolean · default: false

Body

application/json

Response

200

application/json

Contract successfully split/duplicated

get__typename · string

id · string

createdAt · object

updatedAt · object

nextBillingDate · object

status · enum<string>

Available options: ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED, $UNKNOWN

deliveryPrice · object

Show child attributes

lastPaymentStatus · enum<string>

Available options: SUCCEEDED, FAILED, $UNKNOWN

billingPolicy · object

Show child attributes

deliveryPolicy · object

Show child attributes

lines · object

Show child attributes

customerPaymentMethod · object

Show child attributes

deliveryMethod · object

Show child attributes

originOrder · object

Show child attributes

customer · object

Show child attributes

discounts · object

Show child attributes

note · string

customAttributes · object[]

Show child attributes

billingAttempts · object

Show child attributes