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

ID of the Subscription

Response
200

success

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

      Find subscription by deal

      Copy link
      Copy to clipboard
      GET

      /v1/subscriptions/find/{dealId}

      Returns details of an installment or a recurring Subscription by Deal ID.

      Path parameters

      dealId

      integer

      required

      ID of the Deal

      Response
      200

      success

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

          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

          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

            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

            Description of the Recurring Subscription

            cadence_type

            string

            required

            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

            Amount of each payment

            start_date

            string

            required

            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

              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

                ID of the Subscription

                Body parameters

                application/json

                description

                string

                Description of the Recurring Subscription

                cycle_amount

                integer

                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

                  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

                    ID of the Subscription

                    Body parameters

                    application/json

                    end_date

                    string

                    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

                      ID of the Subscription

                      Response
                      200

                      success

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

                          Subscribe to Pipedrive’s Developer Newsletter