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

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

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "[e-mail]",
    "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

200

application/json

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