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.

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

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>'

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount"

headers = {"X-API-Key": "<x-api-key>"}

response = requests.put(url, headers=headers)

print(response.text)

const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount';
const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

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

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

billingAttempts

object

Show child attributes

billingPolicy

object

Show child attributes

createdAt

object

customAttributes

object[]

Show child attributes

customer

object

Show child attributes

customerPaymentMethod

object

Show child attributes

deliveryMethod

object

Show child attributes

deliveryPolicy

object

Show child attributes

deliveryPrice

object

Show child attributes

discounts

object

Show child attributes

get__typename

string

lastPaymentStatus

enum<string>

Available options:

SUCCEEDED,

FAILED,

$UNKNOWN

lines

object

Show child attributes

nextBillingDate

object

note

string

originOrder

object

Show child attributes

status

enum<string>

Available options:

ACTIVE,

PAUSED,

CANCELLED,

EXPIRED,

FAILED,

$UNKNOWN

updatedAt

object

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>'

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount"

headers = {"X-API-Key": "<x-api-key>"}

response = requests.put(url, headers=headers)

print(response.text)

const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount';
const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-apply-discount")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

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

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Apply discount code to subscription

Headers

Query Parameters

Response