# Overview of Subscription API Calls

HTML version: [Overview of Subscription API Calls](https://support.gladstonesoftware.cloud/api-integrations/overview-of-subscription-api-calls)

## Problem
Users need to understand the available Subscription API calls and their purposes for managing subscriptions within the Plus2 database.

## Resolution

1. **Assign a Subscription to a Member**
   - Call `AssignSubTypeToMember(int memberId, string subTypeId, DateTime startDate, string siteId)` to assign a subscription to a member.
   - This will leave an unpaid debt on the member’s account. If payment has been received, use `SetMemberSubPaid` to mark it as paid.

2. **Assign a Subscription with Specific End Date**
   - Use `AssignSubTypeToMemberDate(int memberId, string subTypeId, DateTime startDate, string siteId, DateTime earliestEndDate)` to behave as above, but also specify the earliest end date.

3. **Assign a Subscription with Additional Details**
   - Use `AssignSubTypeToMemberWithDetails(obj requestDetails)` to:
     - Allocate an unpaid subscription to a member for a given start date.
     - Set the earliest end date and renewal stop date.
     - Returns the relevant subscription and invoice details.

4. **Decrement Subscription Usages**
   - Call `DecrementUsagesOnSub(int memberId, int subscriptionRef, int usageCount, string transactionId)` to decrease the number of usages for a subscription by a given amount.
   - The `transactionId` must be unique and cannot be reused. This is to prevent multiple identical calls for a single transaction.
   - If configuration allows, this method may also be used to increment usage counts.

5. **Retrieve Available Subscriptions**
   - Use `GetAllAvailableSubs(int memberId, string siteId, bool webBookableOnly)` to retrieve available subscription types for purchase.
   - Set `memberId` to 0 to view options for non-members.
   - `siteId` can be a single site or a comma-separated list of sites.
   - **Note:** This method is due to be deprecated. Use `GetAvailableSubsByStartDate` instead.

6. **Retrieve Subscriptions with Additional Details**
   - Use `GetAvailableSubsByStartDate(obj request)` to get the same results as above, plus additional price information and the next collection date.

7. **Mark a Subscription as Paid**
   - Call `SetMemberSubPaid(int memberId, string subscriptionRef, bool payAll, int externalAuditId)` to set a subscription’s status to paid.
   - If `payAll` is true, all invoices linked to the subscription will be paid off. If false, only those that are due will be paid.

8. **Stop Subscription Renewal**
   - Use `StopSubscriptionRenewal()` to set the `renewalStopDate`, allowing start-of-day procedures to stop the subscription.
   - It is recommended to set the `AdhereToEarliestEndDate` parameter to true in the request.
   - This returns a `SuccessFailureWithMessage`.

## Notes

- The use of unique `transactionId` in `DecrementUsagesOnSub` prevents duplicate processing of a single transaction.
- `GetAllAvailableSubs` is being replaced by `GetAvailableSubsByStartDate`. Use the newer method for enhanced information.
- For stopping renewals, setting `AdhereToEarliestEndDate` to true is recommended for correct behavior.