Subscription Contracts

Apply discount code to subscription

Applies a Shopify discount code to an existing subscription contract. The discount will be applied to future orders generated by this subscription.

Full behavior, validation rules, and side effects

Key Features:

Validates discount code through Shopify’s discount system
Prevents duplicate discount code applications
Uses database locking to prevent race conditions
Automatically recalculates shipping prices if needed
Creates audit trail through activity logs
Returns updated subscription with discount details

Discount Code Validation:

Must be an active Shopify discount code in the store
Must be applicable to subscription orders
Cannot be applied if already active on the subscription
Subject to Shopify’s discount rules and restrictions

Customer Portal Restrictions: When called from customer portal context:

If ‘enableAllowOnlyOneDiscountCode’ is enabled, customers cannot apply additional codes
This restriction ensures single discount policy enforcement
External API calls bypass this restriction

Concurrency Protection:

Uses database-level locking on the subscription contract
Prevents simultaneous discount applications
Ensures data consistency in high-traffic scenarios

Post-Application Effects:

Discount applies to all future orders from the subscription
May trigger shipping price recalculation
Creates ‘DISCOUNT_APPLIED’ activity log entry
Updates subscription’s discount collection

Important Notes:

Discount codes are case-sensitive
Invalid or expired codes will return appropriate errors
Discounts stack according to Shopify’s combination rules
Some discounts may not be compatible with subscriptions

Authentication: Requires valid X-API-Key header

PUT

/

api

/

external

/

v2

/

subscription-contracts-apply-discount

Apply discount code to subscription

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount \
  --header 'X-API-Key: <x-api-key>'

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 2,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          }
        }
      }
    ]
  },
  "discounts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionManualDiscount/888888",
          "title": "SAVE10",
          "targetType": "ALL_LINES",
          "value": {
            "percentage": 10
          }
        }
      }
    ]
  }
}

Headers

X-API-Key

string

required

API Key for authentication

Query Parameters

contractId

integer<int64>

required

Subscription contract ID to apply discount to. Provide the numeric ID without the gid:// prefix

Required range: x >= 1

api_key

string

API Key (Deprecated - Use X-API-Key header instead)

discountCode

string

required

Valid Shopify discount code to apply. Case-sensitive. Must be an active discount code in your Shopify store.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_-]+$

Response

Discount code successfully applied

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

Replace all line item attributes in bulk across subscription contracts

Add custom discount to subscription

Apply discount code to subscription

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount \
  --header 'X-API-Key: <x-api-key>'

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 2,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          }
        }
      }
    ]
  },
  "discounts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionManualDiscount/888888",
          "title": "SAVE10",
          "targetType": "ALL_LINES",
          "value": {
            "percentage": 10
          }
        }
      }
    ]
  }
}