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.

Full behavior, validation rules, and side effects

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/cp/api/update-custom-note-attributes

Update custom attributes on a subscription contract

cURL

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

200

Success Response

{
  "message": "Attributes updated successfully"
}

Body

application/json

Request to update custom attributes on a subscription contract

subscriptionContractId · integer<int64> · required

The ID of the subscription contract to update

Example:

123456789

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

Response

200

application/json

Attributes successfully updated