Subscriptions

Subscriptions represent the revenue that is occurring over time with payments of varying amounts and payment dates (installment subscription) or over fixed intervals of time with payments of the same amount (recurring subscription).

Get details of a subscription

Copy link
Copy to clipboard
GET

/v1/subscriptions/{id}

Returns details of an installment or a recurring subscription.

Path parameters

id

integer

required

The ID of the subscription

Response
200

Success

Expand all
Copy code
    • true
    • { ... }

    Find subscription by deal

    Copy link
    Copy to clipboard
    GET

    /v1/subscriptions/find/{dealId}

    Returns details of an installment or a recurring subscription by the deal ID.

    Path parameters

    dealId

    integer

    required

    The ID of the deal

    Response
    200

    Success

    Expand all
    Copy code
      • true
      • { ... }

      Get all payments of a subscription

      Copy link
      Copy to clipboard
      GET

      /v1/subscriptions/{id}/payments

      Returns all payments of an installment or recurring subscription.

      Path parameters

      id

      integer

      required

      The ID of the subscription

      Response
      200

      Success

      Expand all
      Copy code
        • true
        • [ ... ]

        Add a recurring subscription

        Copy link
        Copy to clipboard
        POST

        /v1/subscriptions/recurring

        Adds a new recurring subscription.

        Body parameters

        application/json

        deal_id

        integer

        required

        The ID of the deal this recurring subscription is associated with

        currency

        string

        required

        The currency of the recurring subscription. Accepts a 3-character currency code.

        description

        string

        The description of the recurring subscription

        cadence_type

        string

        required

        The interval between payments

        Values

        weekly

        monthly

        quarterly

        yearly

        cycles_count

        integer

        Shows how many payments the subscription has. Note that one field must be set: cycles_count or infinite. If cycles_count is set, then cycle_amount and start_date are also required.

        cycle_amount

        integer

        required

        The amount of each payment

        start_date

        string

        required

        The start date of the recurring subscription. Format: YYYY-MM-DD

        Format

        date

        infinite

        boolean

        This indicates that the recurring subscription will last until it's manually canceled or deleted. Note that only one field must be set: cycles_count or infinite.

        payments

        array

        Array of additional payments. It requires a minimum structure as follows: [{ amount:SUM, description:DESCRIPTION, due_at:PAYMENT_DATE }]. Replace SUM with a payment amount, DESCRIPTION with an explanation string, PAYMENT_DATE with a date (format YYYY-MM-DD).

        update_deal_value

        boolean

        Indicates that the deal value must be set to recurring subscription's MRR value

        Response
        200

        Success

        Expand all
        Copy code
          • true
          • { ... }

          Add an installment subscription

          Copy link
          Copy to clipboard
          POST

          /v1/subscriptions/installment

          Adds a new installment subscription.

          Body parameters

          application/json

          deal_id

          integer

          required

          The ID of the deal this installment subscription is associated with

          currency

          string

          required

          The currency of the installment subscription. Accepts a 3-character currency code.

          payments

          array

          required

          Array of payments. It requires a minimum structure as follows: [{ amount:SUM, description:DESCRIPTION, due_at:PAYMENT_DATE }]. Replace SUM with a payment amount, DESCRIPTION with an explanation string, PAYMENT_DATE with a date (format YYYY-MM-DD).

          update_deal_value

          boolean

          Indicates that the deal value must be set to the installment subscription's total value

          Response
          200

          Success

          Expand all
          Copy code
            • true
            • { ... }

            Update a recurring subscription

            Copy link
            Copy to clipboard
            PUT

            /v1/subscriptions/recurring/{id}

            Updates a recurring subscription.

            Path parameters

            id

            integer

            required

            The ID of the subscription

            Body parameters

            application/json

            description

            string

            The description of the recurring subscription

            cycle_amount

            integer

            The amount of each payment

            payments

            array

            Array of additional payments. It requires a minimum structure as follows: [{ amount:SUM, description:DESCRIPTION, due_at:PAYMENT_DATE }]. Replace SUM with a payment amount, DESCRIPTION with an explanation string, PAYMENT_DATE with a date (format YYYY-MM-DD).

            update_deal_value

            boolean

            Indicates that the deal value must be set to recurring subscription's MRR value

            effective_date

            string

            required

            All payments after that date will be affected. Format: YYYY-MM-DD

            Format

            date

            Response
            200

            Success

            Expand all
            Copy code
              • true
              • { ... }

              Update an installment subscription

              Copy link
              Copy to clipboard
              PUT

              /v1/subscriptions/installment/{id}

              Updates an installment subscription.

              Path parameters

              id

              integer

              required

              The ID of the subscription

              Body parameters

              application/json

              payments

              array

              required

              Array of payments. It requires a minimum structure as follows: [{ amount:SUM, description:DESCRIPTION, due_at:PAYMENT_DATE }]. Replace SUM with a payment amount, DESCRIPTION with a explanation string, PAYMENT_DATE with a date (format YYYY-MM-DD).

              update_deal_value

              boolean

              Indicates that the deal value must be set to installment subscription's total value

              Response
              200

              Success

              Expand all
              Copy code
                • true
                • { ... }

                Cancel a recurring subscription

                Copy link
                Copy to clipboard
                PUT

                /v1/subscriptions/recurring/{id}/cancel

                Cancels a recurring subscription.

                Path parameters

                id

                integer

                required

                The ID of the subscription

                Body parameters

                application/json

                end_date

                string

                The subscription termination date. All payments after specified date will be deleted. Default value is the current date.

                Format

                date

                Response
                200

                Success

                Expand all
                Copy code
                  • true
                  • { ... }

                  Delete a subscription

                  Copy link
                  Copy to clipboard
                  DELETE

                  /v1/subscriptions/{id}

                  Marks an installment or a recurring subscription as deleted.

                  Path parameters

                  id

                  integer

                  required

                  The ID of the subscription

                  Response
                  200

                  Success

                  Expand all
                  Copy code
                    • true
                    • { ... }

                    Subscribe to Pipedrive’s Developer Newsletter