> ## 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.

# Recurring payment notifications (Global-e to Subscription Manager)

> Global-e informs Subscription Manager about recurring payments's updates.

<Note>
  Part of the [Subscription Connector](/subscription-connector) integration guide — see it for when and how to use this endpoint.
</Note>

<Warning>
  This is the one contract in the Subscriptions set that **you implement and Global-e calls**. The server is the Subscription Manager, not Global-e.
</Warning>


## OpenAPI

````yaml api-reference/specs/recurringpaymentnotifications.yaml POST /subscriptions/recurringPayments/notifications
openapi: 3.0.3
info:
  title: Recurring Payment Notifications
  version: '1.4'
  description: >-
    Global-e calls this endpoint to notify Subscription Manager about the status
    of recurring payments. This is the one contract in the Subscriptions set
    that you implement and Global-e calls: the server is the Subscription
    Manager, not Global-e.
servers:
  - url: https://{subscription_manager_domain}
    variables:
      subscription_manager_domain:
        default: subscription-manager-domain
        description: >-
          The Subscription Manager's domain hosting this callback. The platform
          supplies the actual URL to Global-e; the documentation shows it as a
          placeholder.
security: []
tags:
  - name: Recurring payment notifications
    x-page-title: Recurring payment notifications
  - name: 'Direction: Global-e → Subscription Manager'
  - name: 'Domain: Payments'
paths:
  /subscriptions/recurringPayments/notifications:
    post:
      tags:
        - Recurring payment notifications
      summary: Recurring payments notifications
      description: >-
        Global-e informs Subscription Manager about recurring payments's
        updates.
      operationId: recurringPaymentNotifications
      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/RecurringPaymentsNotificationRequest'
            examples:
              payment_success:
                summary: PAYMENT_SUCCESS
                value:
                  notificationType: PAYMENT_SUCCESS
                  subscriptionId: '123456'
                  externalReferenceId: '1234567890'
                  payment:
                    totalAmount: 343.23
                    currencyCode: USD
                    orderId: '1234567890'
              payment_declined:
                summary: PAYMENT_DECLINED
                value:
                  notificationType: PAYMENT_DECLINED
                  subscriptionId: '123456'
                  externalReferenceId: '1234567890'
                  payment:
                    reason:
                      error: Declined by Adyen GW
                      code: ADYEN_GW_ERROR
                      description: Invalid card details. The card is expired.
              payment_canceled:
                summary: PAYMENT_CANCELED
                value:
                  notificationType: PAYMENT_CANCELED
                  subscriptionId: '123456'
                  externalReferenceId: '1234567890'
                  payment:
                    reason:
                      code: MANUAL_CANCELED
                      description: The payment has been manual canceled by operator.
      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_subscription_id:
                  summary: Invalid subscription Id
                  value:
                    error: Invalid subscription Id format
                    code: INVALID_SUBSCRIPTION_ID
                    description: The provided SubscriptionId 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 merchant GUID
        '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: Subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                subscription_not_found:
                  summary: Subscription not found
                  value:
                    error: Order not found
                    code: SUBSCRIPTION_NOT_FOUND
                    description: No subscription found for the specified SubscriptionId.
                external_reference_not_found:
                  summary: External reference not found
                  value:
                    error: External reference not found
                    code: EXTERNAL_REFRENCE_NOT_FOUND
                    description: >-
                      No external reference found for the specified
                      externalReferenceId.
        '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.
components:
  schemas:
    RecurringPaymentsNotificationRequest:
      type: object
      required:
        - notificationType
        - subscriptionId
        - externalReferenceId
        - payment
      properties:
        notificationType:
          type: string
          description: >-
            The notification Global-e is sending, and what the Subscription
            Manager is

            expected to do with it:


            | Type | Description | Expected action |

            | --- | --- | --- |

            | PAYMENT_SUCCESS | Payment completed successfully | Update
            subscription, create invoice |

            | PAYMENT_PENDING | Payment is pending | Mark as pending, wait for
            final status |

            | PAYMENT_DECLINED | Payment was declined | Retry logic or notify
            customer |

            | PAYMENT_CANCELED | Payment was canceled | Cancel or reschedule |
          enum:
            - PAYMENT_SUCCESS
            - PAYMENT_PENDING
            - PAYMENT_DECLINED
            - PAYMENT_CANCELED
        subscriptionId:
          $ref: '#/components/schemas/SubscriptionId'
        externalReferenceId:
          $ref: '#/components/schemas/ExternalReferenceId'
        payment:
          description: Payment details (varies by type)
          oneOf:
            - $ref: '#/components/schemas/PaymentSuccess'
            - $ref: '#/components/schemas/PaymentPending'
            - $ref: '#/components/schemas/PaymentDeclined'
            - $ref: '#/components/schemas/PaymentCanceled'
    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 subscription in the subscription manager.
    ExternalReferenceId:
      type: string
      description: >-
        Unique identifier of external document object, like invoiceId in the
        subscription manager
    PaymentSuccess:
      type: object
      description: Payment object for PAYMENT_SUCCESS.
      required:
        - totalAmount
        - currencyCode
        - orderId
      properties:
        totalAmount:
          type: number
          format: double
          description: Total amount in customer currency
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
        orderId:
          $ref: '#/components/schemas/OrderId'
    PaymentPending:
      type: object
      description: Payment object for PAYMENT_PENDING.
      required:
        - totalAmount
        - currencyCode
        - orderId
      properties:
        totalAmount:
          type: number
          format: double
          description: Total amount in customer currency
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
        orderId:
          $ref: '#/components/schemas/OrderId'
    PaymentDeclined:
      type: object
      description: Payment object for PAYMENT_DECLINED.
      required:
        - reason
      properties:
        reason:
          $ref: '#/components/schemas/Error'
    PaymentCanceled:
      type: object
      description: Payment object for PAYMENT_CANCELED.
      required:
        - reason
      properties:
        reason:
          $ref: '#/components/schemas/Canceled'
    CurrencyCode:
      type: string
      description: ISO 4217 currency code
      pattern: ^[A-Z]{3}$
    OrderId:
      type: string
      description: Unique order identifier in Global-e
    Error:
      type: object
      description: Error structure
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Machine-readable error code
        description:
          type: string
          description: Detailed error description
    Canceled:
      type: object
      description: Cancel structure
      required:
        - code
      properties:
        code:
          type: string
          description: Machine-readable code
        description:
          type: string
          description: Detailed error description

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.