Adding subscriptions

🚧

Breaking change notice

Prior to 20.3.205, subscriptions added with the same BillToPartyId, IsMemberComponent and BillDate values would automatically be added to the same invoice.

With newer versions of iMIS, if the persisted cash invoice feature is enabled, it is required to provide the InvoiceId property when adding a subscription that needs to be included within another invoice. Without providing the InvoiceId, iMIS will create a new invoice for any newly added subscription with a BillAmount not equal to 0.00. See Example: Adding two subscriptions into a single invoice

The subscription endpoint can be used to add a new subscription for a contact. This includes membership fees, chapters, subscriptions, sections, miscellaneous and voluntary items. New subscriptions can either be added as an unbilled subscription or they can be billed at the time it is added, resulting in a new invoice being created. All invoices created as a result of adding a subscription will use the cash accounting method. The following fields are available when adding the subscription.

Fields available when adding a new subscription

• PartyId (required)
• ItemId (required)
• Status (Active = 0, Inactive = 1)
• IsMemberComponent (If true, the subscription will be billed as a membership join/renewal. If false, any resulting invoice will be of type SubscriptionFees.)
• BillBegin
• BillThrough
• BeginDate
• PaidThru
• BilledAmount¹
• InvoiceId²
• BillToPartyId
• BillDate
• IsComplimentary
• DateAdded
• SourceCode
• BillSubscription³ (default is true)

¹ BilledAmount value is ignored if BillSubscription is true.

² InvoiceId can be provided to add a new subscription to an existing cash invoice.

³ When BillSubscription is true (or not provided) then the subscription will be billed using normal pricing rules configured within iMIS. When set to false, you can either:

• Leave the subscription unbilled OR
• Set BilledAmount and/or BillDate to result in an invoice being created with a custom amount rather than using the configured pricing rules.

Price when using BillSubscription is true

If BillSubcription is set to true (or if it's left out of the request) when adding a new subscription, then the subscription will be billed to the contact as according to the price defined in iMIS. This includes both member/non-member pricing and any special pricing rules on the billing item. To see the price ahead of time, you can GET on the PartyItemPrice endpoint like this:

https://{{URL}}/api/PartyItemPrice?PartyId=23215&ItemId=JOUR&EffectiveDate=2026-01-01T00:00:00

The SelectedPrice is the amount that will be charged for the subscription.

Example: Adding a subscription without creating an invoice

If you want to add a subscription for a contact and do not want to create an invoice, the following must all be true:

• BillSubscription must be set to false
• BillDate must not be set
• BillAmount must not set

POST https://{{URL}}/api/Subscription

{
    "PartyId": "23215",
    "ItemId": "JOUR",
    "BillSubscription": false
}

This will add the subscription without any billing dates, amount or InvoiceId. If generate renewals was later run for this contact and the billing cycle selected contained this product, a new invoice would be created at that time. See Generating renewals for more information.

Example: Adding two subscriptions into a single invoice

Note: This example assumes persisted cash invoices have been enabled. If persisted cash invoices have not been enabled on your iMIS system yet, you can still follow this same workflow to ensure your solution continues to work once the feature is enabled.

Add the first subscription with either BillSubscription set to true, or BillAmount, BillBegin and BillThrough set. This example uses the pre-configured pricing rules in iMIS.

POST https://{{URL}}/api/Subscription

{
    "PartyId": "23215",
    "ItemId": "JOUR",
    "BeginDate": "2026-01-01T00:00:00",
    "BillToPartyId": "23215",
    "BillSubscription": true
}

The results returned will look similar to this (empty fields removed from the result for readability).

{
    "PartyId": "23215",
    "ItemId": "JOUR",
    "Item": {
      "Description": "",
      "ItemClass": {
        "ItemClassId": "SUB",
        "Name": "Subscription"
      },
      "ItemCode": "JOUR",
      "ItemId": "JOUR",
      "Name": "Journal"
    },
    "ProductType": "SUB",
    "BillBegin": "2026-01-01T00:00:00",
    "BillThrough": "2026-12-31T00:00:00",
    "BeginDate": "2026-01-01T00:00:00",
    "BilledAmount": {
      "Amount": 95.0000,
      "Currency": {
        "CurrencyCode": "USD",
        "DecimalPositions": 2
      },
      "IsAmountDefined": true
    },
    "Balance": {
      "Amount": 95.0000,
      "Currency": {
        "CurrencyCode": "USD",
        "DecimalPositions": 2
      },
      "IsAmountDefined": true
    },
    "InvoiceId": "8158",
    "Copies": 1,
    "BillToPartyId": "23215",
    "BillDate": "2025-04-29T00:00:00",
    "DateAdded": "2025-04-29T00:00:00",
    "LastUpdated": "2025-04-29T11:12:17.453",
    "UpdatedBy": "BRIANM",
    "BillSubscription": false
  }

Use the InvoiceId from the first subscription add result when adding the second subscription (InvoiceId is 8158 in this example)

POST https://{{URL}}/api/Subscription

{
    "PartyId": "23215",
    "ItemId": "INSIDMAG",
    "BeginDate": "2026-01-01T00:00:00",
    "InvoiceId": "8158",
    "BillToPartyId": "23215",
    "BillSubscription": true
}

The results returned will look similar to this (empty fields removed from the result for readability).

{
    "PartyId": "23215",
    "ItemId": "INSIDMAG",
    "Item": {
      "Description": "A periodic guide for students, newcomers, and seasoned professionals on breaking in, moving up, and making it in the industry.",
      "ItemClass": {
        "ItemClassId": "SUB",
        "Name": "Subscription"
      },
      "ItemCode": "INSIDMAG",
      "ItemId": "INSIDMAG",
      "Name": "Industry Insider Magazine"
    },
    "ProductType": "SUB",
    "BillBegin": "2026-01-01T00:00:00",
    "BillThrough": "2026-12-31T00:00:00",
    "BeginDate": "2026-01-01T00:00:00",
    "BilledAmount": {
      "Amount": 44.9500,
      "Currency": {
        "CurrencyCode": "USD",
        "DecimalPositions": 2
      },
      "IsAmountDefined": true
    },
    "Balance": {
      "Amount": 44.9500,
      "Currency": {
        "CurrencyCode": "USD",
        "DecimalPositions": 2
      },
      "IsAmountDefined": true
    },
    "InvoiceId": "8158",
    "AdjustmentReason": "",
    "AdjustmentAmount": {
      "Currency": {
        "CurrencyCode": "USD",
        "DecimalPositions": 2
      },
      "IsAmountDefined": true
    },
    "Copies": 1,
    "BillToPartyId": "23215",
    "BillDate": "2025-04-29T00:00:00",
    "DateAdded": "2025-04-29T00:00:00",
    "SourceCode": "",
    "LastUpdated": "2025-04-29T11:24:32.19",
    "UpdatedBy": "BRIANM",
    "BillSubscription": false
  }

Paying for a subscription

Using the InvoiceId on the subscription, you can easily retrieve the Invoice and add it to a cart.

GET https://{{URL}}/api/InvoiceSummary/8158

A GET on the InvoiceSummary endpoint will return an invoice that looks a little like this (empty fields removed for readability)

{
    "InvoiceId": "8158",
    "FinancialEntity": {
      "FinancialEntityId": "DEMO",
      "Name": "iMIS International",
      "EntityCode": "DEMO",
      "IsDefault": true
    },
    "InvoiceNumber": "2317",
    "InvoiceDate": "2025-04-29T00:00:00",
    "DueDate": "2025-04-29T00:00:00",
    "BillToParty": {
      "Email": "[email protected]",
      "PartyId": "23215",
      "Id": "23215",
      "UniformId": "77e7fa6d-f551-437c-a0f0-baedd725ecd5",
      "Name": "Demo Contact",
      "Sort": "CONTACT, DEMO"
    },
    "SoldToParty": {
      "Email": "[email protected]",
      "PartyId": "23215",
      "Id": "23215",
      "UniformId": "77e7fa6d-f551-437c-a0f0-baedd725ecd5",
      "Name": "Demo Contact",
      "Sort": "CONTACT, DEMO"
    },
    "Description": "Journal",
    "InvoicePurpose": 12,
    "InvoiceAmount": {
      "Amount": 139.95,
      "Currency": {
        "CurrencyCode": "USD",
        "DecimalPositions": 2
      },
      "IsAmountDefined": true
    },
    "Balance": {
      "Amount": 139.95,
      "Currency": {
        "CurrencyCode": "USD",
        "DecimalPositions": 2
      },
      "IsAmountDefined": true
    },
    "AdditionalAttributes": {
      "$values": [
        {
          "Name": "BillingMemberType",
          "Value": "NM"
        },
        {
          "Name": "SourceSystem",
          "Value": "DUES"
        }
      ]
    },
    "InvoiceKey": "3a1e0a05-02c3-4dc9-95eb-ec09df08fb2a"
  }

It can then be added to the contact's Cart.ComboOrder.Invoice property with a PUT on the cart endpoint.

See also: Allocating payments for subscription invoice

Updating an existing subscription

To modify an existing subscription you would do a GET request to

https://{{URL}}/api/Subscription/~{PartyId}|{ItemId}
For Example:
https://{{URL}}/api/Subscription/~23215|JOUR

and make the necessary changes to the JSON followed by a PUT request to that same endpoint.

Fields available when updating a subscription

• Status¹ ² (Active = 0, Inactive = 1)
• IsMemberComponent
• BillBegin²
• BillThrough²
• BeginDate²
• PaidThru²
• BilledAmount² ³
• ReminderCount
• ReminderDate
• AdjustmentReason
• CancelledAsOf¹
• BillToPartyId¹
• BillDate¹
• IsComplimentary¹
• DateAdded
• SourceCode¹

¹ Updating these fields do not affect existing persisted invoices.

² Not available to update if the AccountingMethod is accrual (Cash = 0, Accrual = 1) and the linked invoice has an open balance.

³ Updating BilledAmount on the subscription will automatically update the Balance and AdjustmentAmount accordingly.

Deleting a subscription

Subscriptions may be deleted unless either of the following are true:

• The subscription is a primary fee for the contact. The subscription's product matches the primary fee product for the contact's customer type.
• The subscription has an open balance. To update the balance for a cash-based subscription, you can either update the BillAmount on the subscription (which will result in the linked invoice being adjusted), or you can adjust the invoice directly, which will also result in the subscription being updated. To remove the balance for an accrual-based subscription, the invoice must be adjusted or reversed.

DELETE https://{{URL}}/api/Subscription/~23215|JOUR