> ## Documentation Index
> Fetch the complete documentation index at: https://developers.appstle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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



## OpenAPI

````yaml /subscription/storefront-api-swagger.json post /subscriptions/cp/api/update-custom-note-attributes
openapi: 3.0.1
info:
  description: >-
    Comprehensive API documentation for the customer-facing subscription portal.
    These APIs enable customers to manage their subscriptions, update billing
    information, modify delivery schedules, and access their account details
    through your storefront.


    **Important**: These APIs must be called from your shop's domain (e.g.,
    https://www.myshop.com/apps/subscriptions/cp/api/**) and require customer
    authentication. Unauthenticated requests will return a 401 Unauthorized
    error.
  title: Storefront APIs
  version: 0.0.1
servers:
  - url: https://www.myshop.com/apps
security: []
tags:
  - description: >-
      Core customer portal APIs for managing customer account settings,
      authentication, and portal configurations.
    name: Customer Portal
  - description: >-
      APIs for customers to view and manage their subscription contracts
      including status updates, frequency changes, and cancellations.
    name: Subscription Management
  - description: >-
      APIs for retrieving and updating subscription contract details — delivery
      schedules, line items, addresses, billing cycles.
    name: Subscription Contracts
  - description: >-
      APIs for retrieving available subscription plans and selling plan
      configurations exposed to customers.
    name: Subscription Plans
  - description: >-
      APIs for managing one-time add-on products that can be purchased alongside
      recurring subscription items.
    name: Subscription One-Time Products
  - description: >-
      APIs for retrieving aggregated subscription data and account-level
      subscription information for the signed-in customer.
    name: Subscription Data
  - description: >-
      APIs for managing customizable product boxes and bundles where customers
      can select multiple items.
    name: Build-a-Box & Bundles
  - description: >-
      APIs for managing payment methods, billing information, and processing
      subscription payments.
    name: Billing & Payments
  - description: >-
      APIs for retrieving product information, selling plans, variant data, and
      subscription-enabled products available to customers.
    name: Product Catalog
  - description: >-
      APIs for managing delivery schedules, shipping addresses, delivery
      methods, and tracking order status.
    name: Delivery & Shipping
  - description: >-
      APIs for handling subscription cancellations, retention activities, and
      customer feedback management.
    name: Customer Retention
  - description: >-
      APIs for integrating loyalty programs with subscriptions including points
      redemption and earning options.
    name: Loyalty Integration
  - description: >-
      APIs for accessing portal customization settings, translations, and theme
      configurations.
    name: Customization
  - description: >-
      APIs for retrieving promotional campaigns shown in the customer portal,
      tracking banner engagement, and redeeming campaign offers.
    name: Campaigns
  - description: >-
      APIs for local pickup and click-and-collect — listing pickup locations and
      resolving eligible pickup dates and time slots.
    name: Store Pickup
paths:
  /subscriptions/cp/api/update-custom-note-attributes:
    post:
      tags:
        - Subscription Management
        - Subscription Contracts
      summary: Update custom attributes on a subscription contract
      description: >-
        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
      operationId: updateOrderNoteAttributes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAttributesRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                Success Response:
                  description: Success Response
                  value:
                    message: Attributes updated successfully
          description: Attributes successfully updated
        '400':
          content:
            application/json:
              examples:
                Contract Not Found:
                  description: Contract Not Found
                  value:
                    detail: No subscription contract found with the specified ID
                    status: 400
                    title: UserGeneratedError:Subscription contract not found
                    type: https://example.com/errors/bad-request
                Missing Contract ID:
                  description: Missing Contract ID
                  value:
                    detail: Subscription contract ID is required
                    status: 400
                    title: Validation Error
                    type: https://example.com/errors/bad-request
          description: Invalid request parameters
        '401':
          description: Authentication required - missing or invalid API key
        '403':
          description: Insufficient permissions to update subscription contracts
components:
  schemas:
    UpdateAttributesRequest:
      description: Request to update custom attributes on a subscription contract
      properties:
        customAttributesList:
          description: >-
            List of custom attributes to set on the subscription contract. Each
            attribute is a key-value pair that will be stored with the
            subscription.
          items:
            $ref: '#/components/schemas/OrderNoteAttribute'
          type: array
        subscriptionContractId:
          description: The ID of the subscription contract to update
          example: 123456789
          format: int64
          type: integer
      required:
        - customAttributesList
        - subscriptionContractId
      type: object
    OrderNoteAttribute:
      description: A custom attribute consisting of a key and value
      properties:
        key:
          description: >-
            The attribute key. Should be a unique identifier for this attribute.
            Use descriptive keys like 'gift_message', 'delivery_instructions',
            etc.
          example: gift_message
          type: string
        value:
          description: >-
            The attribute value. Can be any string value including JSON-encoded
            data. Set to empty string to clear an attribute.
          example: Happy Birthday! Enjoy your subscription!
          type: string
      required:
        - key
      type: object

````