> ## 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. # Subscription notifications (Subscription Manager to Global-e) > Subscription Manager informs Global-e about subscription's updates. Part of the [Subscription Connector](/subscription-connector) integration guide — see it for when and how to use this endpoint. ## OpenAPI ````yaml api-reference/specs/subscriptionnotifications.yaml POST /subscriptions/notifications openapi: 3.0.3 info: title: Subscription Notifications version: '1.4' description: >- This endpoint allows the Subscription Manager to inform Global-e about subscription lifecycle events. 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: Subscription notifications x-page-title: Subscription notifications - name: 'Direction: Subscription Manager → Global-e' - name: 'Domain: Payments' paths: /subscriptions/notifications: post: tags: - Subscription notifications summary: Subscriptions updates notifications description: Subscription Manager informs Global-e about subscription's updates. operationId: subscriptionNotifications parameters: - 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/SubscriptionNotificationRequest' responses: '202': description: Request accepted. content: application/json: schema: $ref: '#/components/schemas/Success' examples: accepted: summary: Request received successfully value: description: Request received successfully! '400': description: Bad Request - Invalid input data content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_order_id: summary: Invalid Order ID value: error: Invalid OrderId format code: INVALID_ORDER_ID description: The provided OrderId is not in the correct format. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Unauthorized value: error: Invalid API Key code: UNAUTHORIZED description: Invalid API Key '403': description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficient_permissions: summary: Insufficient permissions value: 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/ErrorResponse' examples: subscription_details_not_found: summary: Subscription details not found value: error: Subscription details not found code: SUBSCRIPTION_DETAILS_NOT_FOUND description: >- No subscription details found for the specified subscriptionId. order_not_found: summary: Order not found value: error: Order not found code: ORDER_NOT_FOUND description: No order found for the specified OrderId. '409': description: Conflict - Idempotency key conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: idempotency_key_conflict: summary: Idempotency key conflict value: error: Idempotency key conflict code: IDEMPOTENCY_KEY_CONFLICT description: >- Request already in use. Use a different Idempotency-Key for new operation. '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: summary: Internal server error value: error: Internal server error code: INTERNAL_ERROR description: An unexpected error occurred while processing the request. default: description: General error structure content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: curl source: >- curl -X POST "https://{globale_api_domain}/subscriptions/notifications" \ -H "Authorization: Bearer {JWT Token}" \ -H "Idempotency-Key: 3f1a7c2e-9b40-4d6f-8a21-5c9e0b7d4a11" \ -H "Content-Type: application/json" \ -d '{"notificationType":"SUBSCRIPTION_CREATED","subscriptionId":"123456","merchantGuid":"1234567890","orderId":"1234567890","externalReferenceId":"INV-001","products":["PROD-001","PROD-002"]}' components: schemas: SubscriptionNotificationRequest: type: object required: - notificationType - subscriptionId - merchantGuid properties: notificationType: type: string description: |- Which subscription lifecycle event this notification reports. - `SUBSCRIPTION_CREATED` — a subscription has been created - `ADDRESS_UPDATE` — the subscription's shipping address has changed enum: - SUBSCRIPTION_CREATED - ADDRESS_UPDATE subscriptionId: $ref: '#/components/schemas/SubscriptionId' merchantGuid: $ref: '#/components/schemas/MerchantGuid' oneOf: - $ref: '#/components/schemas/SubscriptionCreatedNotificationRequest' - $ref: '#/components/schemas/AddressUpdateNotificationRequest' discriminator: propertyName: notificationType mapping: SUBSCRIPTION_CREATED: '#/components/schemas/SubscriptionCreatedNotificationRequest' ADDRESS_UPDATE: '#/components/schemas/AddressUpdateNotificationRequest' example: notificationType: SUBSCRIPTION_CREATED subscriptionId: '123456' merchantGuid: '1234567890' orderId: '1234567890' externalReferenceId: '1234567890' products: - PROD-001 Success: type: object required: - description properties: description: type: string description: Human-readable message 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 SubscriptionId: type: string maxLength: 100 description: Unique identifier of subscription in the subscription manager. MerchantGuid: type: string format: uuid description: Global-e merchant unique identifier SubscriptionCreatedNotificationRequest: type: object description: A subscription creation event. required: - orderId - products properties: orderId: $ref: '#/components/schemas/OrderId' externalReferenceId: $ref: '#/components/schemas/ExternalReferenceId' products: $ref: '#/components/schemas/ProductsCodes' AddressUpdateNotificationRequest: type: object description: >- A subscription shipping-address update event. Carries no fields beyond the three common ones; the new address is read from the subscription itself. OrderId: type: string description: Unique order identifier in Global-e ExternalReferenceId: type: string description: >- Unique identifier of external document object, like invoiceId in the subscription manager ProductsCodes: type: array description: List of products codes minItems: 1 items: $ref: '#/components/schemas/ProductCode' ProductCode: type: string description: Unique product identifier ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.