> ## 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/admin-api-swagger.json post /api/external/v2/update-custom-note-attributes openapi: 3.0.1 info: description: >- Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications. title: Admin APIs version: 0.0.1 servers: - url: https://subscription-admin.appstle.com security: [] tags: - description: >- Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions. name: Subscription Management - description: >- APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information. name: Subscription Payments - description: >- APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses. name: Subscription Contracts - description: >- APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products. name: Subscription Products - description: >- APIs for handling billing operations, payment processing, and financial transactions related to subscriptions. name: Billing & Payments - description: >- APIs for managing discounts and promotional codes applied to subscriptions. name: Subscription Discounts - 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 managing subscription plans, pricing tiers, and plan configurations. name: Subscription Plans - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing the product catalog including product information, variants, and inventory. name: Product Catalog - description: >- APIs for managing operational settings, configurations, and administrative functions. name: Operations & Settings - description: >- APIs powering the customer-facing portal where subscribers can manage their own subscriptions. name: Customer Portal - description: APIs for managing customer information, profiles, and account details. name: Customers - description: >- APIs for retrieving aggregated subscription data, customer subscription history, and account-level subscription information. name: Subscription Data - description: >- APIs for managing delivery profiles, shipping rates, free shipping configuration, and delivery method options on subscriptions. name: Delivery & Shipping - description: >- APIs for managing storefront customization including custom CSS, theme settings, label translations, and merchant-defined widget configuration. name: Customization - description: >- APIs for configuring cancellation flows, retention offers, cancellation reason management, and win-back automation. name: Customer Retention paths: /api/external/v2/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 parameters: - deprecated: true description: API Key (Deprecated) in: query name: api_key required: false schema: type: string - description: API Key in: header name: X-API-Key required: true schema: type: string - description: Merge or replace mode in: query name: overwriteExistingAttributes required: false schema: default: true type: boolean 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 ````