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

# Add Mandate

> This API is used to update a specific subscription with a new payment method. Only `ACTIVE` or `PAUSED` subscriptions can be updated with a new payment method. If a subscription has `cancelAtEnd` set to `true`, this API cannot be called, since the subscription will be automatically canceled at the end of the cycle and adding a new mandate will be useless.

For `PENDING` subscriptions (which have not been activated once), always use the `payURL` provided in the [Get Subscription API](/api-reference/subscription/get-subscription).

This API will not work for subscriptions in terminal states.

**Note:** Update Mandate, by default, only allows adding a new mandate for a running subscription. If the partner wants, it is possible to request a mandate with the last due unpaid invoice amount. This way, the partner will have a new mandate for auto-debit, and an unpaid invoice will be cleared. This feature can be enabled by requesting the administrative team.



## OpenAPI

````yaml /api-reference/Mandate/mand.json post /subscription/v1.0/updateSubscriptionMandate
openapi: 3.0.3
info:
  title: Mandate API
  description: API's to add and get mandate information.
  version: 1.0.0
servers:
  - url: https://sandbox-api.transactbridge.com
    description: Sandbox Environment
  - url: https://api.transactbridge.com
    description: Production Environment
security:
  - ApiKeyAuth: []
    SignatureAuth: []
paths:
  /subscription/v1.0/updateSubscriptionMandate:
    post:
      tags:
        - Mandate
      summary: Add Mandate
      description: >-
        This API is used to update a specific subscription with a new payment
        method. Only `ACTIVE` or `PAUSED` subscriptions can be updated with a
        new payment method. If a subscription has `cancelAtEnd` set to `true`,
        this API cannot be called, since the subscription will be automatically
        canceled at the end of the cycle and adding a new mandate will be
        useless.


        For `PENDING` subscriptions (which have not been activated once), always
        use the `payURL` provided in the [Get Subscription
        API](/api-reference/subscription/get-subscription).


        This API will not work for subscriptions in terminal states.


        **Note:** Update Mandate, by default, only allows adding a new mandate
        for a running subscription. If the partner wants, it is possible to
        request a mandate with the last due unpaid invoice amount. This way, the
        partner will have a new mandate for auto-debit, and an unpaid invoice
        will be cleared. This feature can be enabled by requesting the
        administrative team.
      operationId: Add Mandate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - subscriptionId
                - returnUrl
              properties:
                subscriptionId:
                  type: string
                  description: Subscription which requires mandate to be updated.
                  format: MongoId
                returnUrl:
                  type: string
                  description: >-
                    This URL is needed to redirect the user after the mandate is
                    completed. If this is not passed, we take subscription
                    returnUrl and redirect the customer to that URL.
                pendingUrl:
                  type: string
                  description: >-
                    If the mandate is still in pending state, the customer will
                    be redirected to this URL. If returnUrl is passed, this
                    parameter is not mandatory.
                successUrl:
                  type: string
                  description: >-
                    If the mandate is in successful state, the customer will be
                    redirected to this URL. If returnUrl is passed, this
                    parameter is not mandatory.
                failedUrl:
                  type: string
                  description: >-
                    If the mandate is in failed state, the customer will be
                    redirected to this URL. If returnUrl is passed, this
                    parameter is not mandatory.
      responses:
        '200':
          description: Specific mandate details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/addMandate'
components:
  schemas:
    addMandate:
      type: object
      properties:
        status:
          type: string
          description: The response from the API
        sub_status:
          type: string
          description: Used for internal purposes only
        data:
          type: object
          description: Contains the mandateId and URL.
          properties:
            mandateId:
              type: string
              description: Transact Bridge mandate Id
            url:
              type: string
              description: URL to redirect the user after the session is completed.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Merchant API Key
    SignatureAuth:
      type: apiKey
      in: header
      name: x-signature
      description: Generated request signature

````

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