> ## Documentation Index > Fetch the complete documentation index at: https://docs.global-e.com/llms.txt > Use this file to discover all available pages before exploring further. # Update a subscription (Subscription Manager to Global-e) > Subscription Manager calls Global-e to patch an existing subscription. Only the fields present in the request body are updated. Currently the only patchable field is the shipping address; its country cannot be changed (same country only). Part of the [Subscription Connector](/subscription-connector) integration guide — see it for when and how to use this endpoint. ## OpenAPI ````yaml api-reference/specs/updatesubscription.yaml PATCH /subscriptions/{subscriptionId} openapi: 3.0.3 info: title: Update Subscription version: '1.4' description: >- This endpoint allows the Subscription Manager to update an existing subscription. Only the fields present in the request body are updated. Currently the only patchable field is the shipping address; its country cannot be changed (same country only). servers: - url: https://{globale_api_domain} variables: globale_api_domain: default: globale_api_domain description: Global-e API host, supplied to the merchant by Global-e. security: [] tags: - name: Subscriptions x-page-title: Update a subscription - name: 'Direction: Subscription Manager → Global-e' - name: 'Domain: Payments' paths: /subscriptions/{subscriptionId}: patch: tags: - Subscriptions summary: Update a subscription description: >- Subscription Manager calls Global-e to patch an existing subscription. Only the fields present in the request body are updated. Currently the only patchable field is the shipping address; its country cannot be changed (same country only). operationId: updateSubscription parameters: - name: subscriptionId in: path required: true description: Unique identifier of the subscription to update. schema: $ref: '#/components/schemas/SubscriptionId' - name: Idempotency-Key in: header required: true description: >- Unique identifier for the request; the same value must be sent on retries so the operation is applied at most once. schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSubscriptionRequest' example: merchantGuid: '1234567890' shippingAddress: firstName: Jane lastName: Doe address1: Mariahilfer Strasse 10 address2: Apt 4 city: Berlin stateOrProvince: Berlin stateCode: BE zip: '10115' countryCode: DE phone: +49 30 1234567 email: jane.doe@example.com responses: '204': description: >- No Content - the subscription was updated; no response body is returned. '400': description: Bad Request - the request body is malformed or unparseable content: application/json: schema: $ref: '#/components/schemas/ErrorResponses' examples: malformed_body: summary: Malformed request body value: errors: - error: Validation failed code: VALIDATION_FAILED description: The provided first order is invalid '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponses' examples: unauthorized: summary: Unauthorized value: errors: - error: Invalid API Key code: UNAUTHORIZED description: Invalid API Key '403': description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponses' examples: insufficient_permissions: summary: Insufficient permissions value: errors: - error: Access denied code: INSUFFICIENT_PERMISSIONS description: >- User does not have permission to perform the operation. '404': description: Object not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponses' examples: subscription_details_not_found: summary: Subscription details not found value: errors: - error: Subscription details not found code: SUBSCRIPTION_DETAILS_NOT_FOUND description: >- No subscription details found for the specified subscriptionId. '409': description: Conflict - Idempotency key conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponses' examples: idempotency_key_conflict: summary: Idempotency key conflict value: errors: - error: Idempotency key conflict code: IDEMPOTENCY_KEY_CONFLICT description: >- Request already in use. Use a different Idempotency-Key for new operation. '422': description: >- Unprocessable Content - the shipping address failed validation or a country change was attempted content: application/json: schema: $ref: '#/components/schemas/ErrorResponses' examples: invalid_shipping_address: summary: Invalid shipping address value: errors: - error: Invalid shipping address code: INVALID_ADDRESS description: 'zip: invalid postal code for the destination country.' country_change_not_allowed: summary: Country change not allowed value: errors: - error: Country change not allowed code: COUNTRY_CHANGE_NOT_ALLOWED description: >- The shipping address country cannot be changed for an existing subscription. '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponses' examples: internal_error: summary: Internal server error value: errors: - error: Internal server error code: INTERNAL_ERROR description: >- An unexpected error occurred while processing the request. x-codeSamples: - lang: curl source: |- curl -X PATCH "https://{globale_api_domain}/subscriptions/123456" \ -H "Authorization: Bearer {JWT Token}" \ -H "Idempotency-Key: 3f1a7c2e-9b40-4d6f-8a21-5c9e0b7d4a11" \ -H "Content-Type: application/json" \ -d '{"merchantGuid":"1234567890","shippingAddress":{"firstName":"Jane","lastName":"Doe","address1":"Mariahilfer Strasse 10","city":"Berlin","zip":"10115","countryCode":"DE"}}' components: schemas: SubscriptionId: type: string maxLength: 100 description: Unique identifier of subscription in the subscription manager. UpdateSubscriptionRequest: type: object description: >- Request to patch an existing subscription. Only the properties present in the request are updated. Currently only shippingAddress is supported. required: - merchantGuid properties: merchantGuid: $ref: '#/components/schemas/MerchantGuid' shippingAddress: allOf: - $ref: '#/components/schemas/ShippingAddress' description: Full new shipping address; replaces the current one. ErrorResponses: type: object description: >- Envelope for collect-all validation errors. May contain several entries, reporting every failing field together. required: - errors properties: errors: type: array minItems: 1 items: $ref: '#/components/schemas/ErrorResponse' MerchantGuid: type: string format: uuid description: Global-e merchant unique identifier ShippingAddress: type: object description: >- Shipping address of the subscription. The full address must be supplied; it replaces the current shipping address. The country cannot be changed. required: - firstName - lastName - address1 - city - zip - countryCode properties: firstName: type: string description: Recipient first name lastName: type: string description: Recipient last name address1: type: string description: Primary address line (street and number) address2: type: string description: Secondary address line (apartment, suite, etc.) city: type: string description: City stateOrProvince: type: string description: State / province name, when applicable stateCode: type: string description: State / province code; required for countries that use subdivisions zip: type: string description: Postal / ZIP code countryCode: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 country code. Must match the current subscription country phone: type: string description: Recipient contact phone number email: type: string format: email description: Recipient contact email address ErrorResponse: type: object description: Error response structure required: - error - code properties: error: type: string description: Human-readable error message code: type: string description: >- Machine-readable error code. Codes documented for the Subscriptions integration: | Code | HTTP status | Description | Typical cause | | --- | --- | --- | --- | | INVALID_ORDER_ID | 400 | Invalid order ID format | Malformed order ID | | INVALID_SUBSCRIPTION_ID | 400 | Invalid subscription ID | Malformed subscription ID | | INVALID_PRODUCT_CODE | 400 | Invalid product code | Unknown product code | | UNAUTHORIZED | 401 | Authentication failed | Invalid or missing credentials | | INSUFFICIENT_PERMISSIONS | 403 | Insufficient permissions | User lacks required permissions | | ORDER_NOT_FOUND | 404 | Order not found | Order ID doesn't exist | | SUBSCRIPTION_NOT_FOUND | 404 | Subscription not found | Subscription ID doesn't exist | | SUBSCRIPTION_DETAILS_NOT_FOUND | 404 | Subscription details not found | Details not found in Global-e | | PRODUCT_NOT_FOUND | 404 | Product not found | Product code doesn't exist | | EXTERNAL_REFERENCE_NOT_FOUND | 404 | External reference not found | Invalid externalReferenceId | | IDEMPOTENCY_KEY_CONFLICT | 409 | Idempotency key conflict | Duplicate idempotency key | | NO_SHIPPING_OPTION_AVAILABLE | 422 | No shipping option available | No shipping option for the subscription's destination | | INVALID_ADDRESS | 422 | Shipping address failed validation | Address failed validation on address update | | COUNTRY_CHANGE_NOT_ALLOWED | 422 | Country change rejected | The shipping address country cannot be changed | | VALIDATION_FAILED | 422 | Validation failed | Missing/invalid field | | INTERNAL_ERROR | 500 | Internal server error | Unexpected server error | description: type: string description: Detailed error description ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.