this article lists the changes made to the API according to the API versioning standards in Perfect Gym. 

Changes in API v2.2

Non-breaking changes in API v2.2

OData Members

New property IsDefualt for paymentSource. Previously when fetching a member profile via the GET /Member API, the response includes payment sources, but it does not indicate which one is the default payment method.

OData PaymentPlans

New properties added:

• CurrentMembershipFeeId
• CurrentAdminFeeId
• CurrentJoiningFeeId

These properties reference the current membership, admin, and joining fees including all applicable taxes.

These fields should be used instead of membershipFee, adminFee, and joiningFee, as the legacy fields do not include all taxes.

Calculated tax values are not stored at the PaymentPlan level. Tax amounts depend on the Club, and are computed dynamically at the Contract level.  

To determine the applicable tax rate for a membership fee used in a specific PaymentPlan and valid for a particular Club, you can use the following two-step approach:

• Retrieve the taxes linked to the current membership fee for a payment plan:

/odata/PaymentPlans?$expand=currentMembershipFee($expand=taxes)

This will return the list of PaymentPlans with their currentMembershipFee, along with the list of related Tax entities.

• Retrieve the tax rates that apply to a specific club and tax:

/odata/Clubs?$filter=id eq 1&$expand=TaxRates($filter=id eq 1;$expand=Tax)

This fetches the TaxRate applicable to Club with id = 1 and Tax with id = 1, along with details of the tax itself.

Since tax rates are not stored directly on the PaymentPlan, you need to extract the TaxId from the CurrentMembershipFee in step 1 and use that TaxId to query the relevant TaxRate for the selected Club in step 2

This pattern allows you to correctly determine the gross membership fee by identifying the applicable tax rate dynamically per club.

 

If your organization uses only one tax and does not differentiate rates across clubs, you can rely directly on the net and gross values of the currentMembershipFee:

​​​​​​​/odata/PaymentPlans?$expand=currentMembershipFee

In this case, currentMembershipFee.net and ​​​​​​​currentMembershipFee.gross already include the applicable tax and no additional tax resolution is required.  

OData Product

New property added:

• AdditionalTaxes

This property exposes additional applicable taxes for a product

Breaking changes in API v2.2

OData PaymentPlans

More records may be returned - there will be contained records with property membershipTypeId having null value.

OData TransactionInvoiceItems

transactionId property has been replaced by 4 properties

• transactionId
• transactionPaymentId
• contractChargeId
• contractPaymentId

with corresponding expandable objects to better illustrate which exact transactions are attached to the invoice item.

Bookings area REST endpoints

1. Removed obsolete CancelClassBooking endpoint
2. CancelSingleBooking endpoint possible error codes changed: It was:

   CancelLimitExceeded, 
   ClassNotBooked, 
   MakeUpProductLimitReached, 
   NotAllowedToCancelByMember, 
   NotEnoughProductsInWarehouse, 
   ToLateToCancel, 
   UnknownError
   

   Now it is:

   BookingDoesNotExist,
   CancelLimitExceeded,
   CancellingByMemberIsDisabled,
   TimeLimitReached,
   UnknownError

3. CancelMemberBookingsForClass endpoint possible error codes changed:It was:

   CancelLimitExceeded,
   ClassNotBooked,
   MakeUpProductLimitReached,
   NotAllowedToCancelByMember,
   NotEnoughProductsInWarehouse,
   ToLateToCancel,
   UnknownError
   

   Now it is:

   BookingDoesNotExist,
   CancelLimitExceeded,
   CancellingByMemberIsDisabled,
   TimeLimitReached,
   UnknownError
   

4. BookClass endpoint possible error codes changed: It was:

   ActivityLevelRequirementNotMet,
   AgeRequirementNotMet,
   BookingCommentsAreTooLong,
   BookingIsUnavailableForThisApp,
   BookingNotAllowed,
   BookingRejected,
   BookingTooLate,
   BookingTooSoon,
   BookingWithoutActiveContractNotAllowed,
   BookingWithOutstandingDebtNotAllowed,
   ClassAlreadyBooked,
   DailyBookingLimitReached,
   DailyZoneBookingLimitReached,
   EventDeleted,
   GlobalBookingLimitReached,
   GuestLimitReached,
   MultibookingExceededAvailableSlots,
   NotAllowedToBookMultipleEventsPerDayAtTheSameTime,
   OutOfHoursAccess,
   StandbyListLimitReached,
   UnknownError,
   UserBannedFromBooking,
   UserHasNoProductWhichAllowsBooking,
   UserHasOtherCalendarEventAtRequestedTime,
   UserNotAllowedToAccessClub,
   UserNotAllowedToAccessZone
   

   Now it is:

   BookingBlockedDueToBlockingNote,
   BookingBlockedForUser,
   BookingTimeLimitExceeded,
   BookingUnavailableForSpecifiedApp,
   ClassesAlreadyBooked,
   DailyBookingLimitReached,
   DailyZoneBookingLimitReached,
   EventIsDeleted,
   GlobalActiveBookingLimitReached,
   GuestLimitReached,
   IncorrectNumberOfSlots,
   NoPermissionToBookSomeoneForClass,
   StandbyLimitReached,
   TooLongCommentsSection,
   TooSoonToBook,
   UnknownError,
   UserAlreadyHasPreReservationForThisClass,
   UserDoesNotMeetAgeLimit,
   UserDoesNotMeetSkillRequirements,
   UserHasNoActiveContractInDate,
   UserHasNoProductToBookOutOfHours,
   UserHasNotRequiredProductToBook,
   UserHasOtherCalendarEventAtRequestedTime,
   UserNotAllowedInZone,
   UserNotAllowedToAccessClubByMembership,
   UserNotAllowedToAccessClubInClassTime,
   UserNotAllowedToBook,
   UserOnFinancialDebit

Changes in API v2.1

Breaking changes in API v2.1

OData PaymentPlans endpoint do not provide translations any more

Fields have been removed from the result items:

• displayName
• descriptionShort
• descriptionLong

PaymentPlans endpoint now returns no translated names (it no longer uses "Accept-Language" HTTP header) only.

Translated names are available in PaymentPlanTranslations endpoint.

PaymentPlanTranslations result got new field:

• descriptionLong

endpoint MemberAgreements/Set has been replaced by MemberAgreements/SetOrUpdate

Non-breaking changes in API v2.1

new endpoints:

• ClassBooking/CancelSingleBooking
• ClassBooking/CancelMemberBookingsForClass
• odata/Crm2ConsultantAvailability
• odata/Crm2Events
• Crm2/ConvertLeadToGuestMember
• Transactions/AddPaymentRefund
• Transactions/AddContractCharge

changes in existing endpoints:

• parameter canBePurchasedOnlyOneTime in endpoint Products/AddProduct
• parameter paymentPlanId in endpoint Marketing/ValidateVoucherCode
• property isAdditionallyPaid in OData ClassCategory data model
• property isdeleted, version in OData ContractDiscountDefinition data model
• property creationDateTime in OData Crm2Lead  data model
• property isRequired in OData CustomAttributeDefinition  data model
• property memberType in OData Member  data model
• property descriptionLong in OData PaymentPlanTranslation  data model
• property canBePurchasedOnlyOneTime in OData Product  data model