Subscription Management

Update custom attributes on a subscription contract

Updates or replaces custom key-value attributes on a subscription contract. These attributes are stored with the subscription and can be used to track custom data, preferences, or metadata that’s important for your business processes.

Custom Attributes Overview: Custom attributes are key-value pairs that allow you to store additional information on subscriptions. They are:

Visible in the Shopify admin and accessible via API
Included in order data when subscription orders are created
Preserved across subscription lifecycle events
Useful for integrations and custom workflows

Update Modes:

Merge Mode (overwriteExistingAttributes=false): Adds new attributes and updates existing ones with matching keys. Other attributes remain unchanged.
Replace Mode (overwriteExistingAttributes=true): Completely replaces all existing attributes with the provided list.

Common Use Cases:

Store gift messages or special instructions
Track referral sources or marketing campaigns
Add internal reference numbers or tracking codes
Store customer preferences or customization options
Integration data for third-party systems

Important Notes:

Attribute keys should not conflict with Shopify’s reserved attributes
Both keys and values are stored as strings
Changes are logged in the activity history
Invalid discount codes may be automatically removed during update

Authentication: Requires valid X-API-Key header

POST

subscriptions

api

update-custom-note-attributes

Update custom attributes on a subscription contract

curl --request POST \
  --url https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes \
  --header 'Content-Type: application/json' \
  --data '
{
  "customAttributesList": [
    {
      "key": "gift_message",
      "value": "Happy Birthday! Enjoy your subscription!"
    }
  ],
  "subscriptionContractId": 123456789
}
'

import requests

url = "https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes"

payload = {
    "customAttributesList": [
        {
            "key": "gift_message",
            "value": "Happy Birthday! Enjoy your subscription!"
        }
    ],
    "subscriptionContractId": 123456789
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    customAttributesList: [{key: 'gift_message', value: 'Happy Birthday! Enjoy your subscription!'}],
    subscriptionContractId: 123456789
  })
};

fetch('https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    customAttributesList: [{key: 'gift_message', value: 'Happy Birthday! Enjoy your subscription!'}],
    subscriptionContractId: 123456789
  })
};

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://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customAttributesList' => [
        [
                'key' => 'gift_message',
                'value' => 'Happy Birthday! Enjoy your subscription!'
        ]
    ],
    'subscriptionContractId' => 123456789
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes"

	payload := strings.NewReader("{\n  \"customAttributesList\": [\n    {\n      \"key\": \"gift_message\",\n      \"value\": \"Happy Birthday! Enjoy your subscription!\"\n    }\n  ],\n  \"subscriptionContractId\": 123456789\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	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://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customAttributesList\": [\n    {\n      \"key\": \"gift_message\",\n      \"value\": \"Happy Birthday! Enjoy your subscription!\"\n    }\n  ],\n  \"subscriptionContractId\": 123456789\n}"

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

{
  "message": "Attributes updated successfully"
}

Body

application/json

Request to update custom attributes on a subscription contract

customAttributesList

object[]

required

List of custom attributes to set on the subscription contract. Each attribute is a key-value pair that will be stored with the subscription.

Show child attributes

subscriptionContractId

integer<int64>

required

The ID of the subscription contract to update

Example:

123456789

Response

Attributes successfully updated

Update custom attributes on a subscription contract

curl --request POST \
  --url https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes \
  --header 'Content-Type: application/json' \
  --data '
{
  "customAttributesList": [
    {
      "key": "gift_message",
      "value": "Happy Birthday! Enjoy your subscription!"
    }
  ],
  "subscriptionContractId": 123456789
}
'

import requests

url = "https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes"

payload = {
    "customAttributesList": [
        {
            "key": "gift_message",
            "value": "Happy Birthday! Enjoy your subscription!"
        }
    ],
    "subscriptionContractId": 123456789
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    customAttributesList: [{key: 'gift_message', value: 'Happy Birthday! Enjoy your subscription!'}],
    subscriptionContractId: 123456789
  })
};

fetch('https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    customAttributesList: [{key: 'gift_message', value: 'Happy Birthday! Enjoy your subscription!'}],
    subscriptionContractId: 123456789
  })
};

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://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customAttributesList' => [
        [
                'key' => 'gift_message',
                'value' => 'Happy Birthday! Enjoy your subscription!'
        ]
    ],
    'subscriptionContractId' => 123456789
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes"

	payload := strings.NewReader("{\n  \"customAttributesList\": [\n    {\n      \"key\": \"gift_message\",\n      \"value\": \"Happy Birthday! Enjoy your subscription!\"\n    }\n  ],\n  \"subscriptionContractId\": 123456789\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	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://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customAttributesList\": [\n    {\n      \"key\": \"gift_message\",\n      \"value\": \"Happy Birthday! Enjoy your subscription!\"\n    }\n  ],\n  \"subscriptionContractId\": 123456789\n}"

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

{
  "message": "Attributes updated successfully"
}

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Update custom attributes on a subscription contract

Body

Response