Archive

Archive for the ‘Rates/Pricing’ Category

BulkData GetBulkRates Method

April 13, 2017 Leave a comment

Retrieves a list of units that have had a rate change up to 48 hours in the past.

Parameters

Name Data Type Is Required
OrgID Long Required
Description The organization’s ID number.
BeginDate DateTime Required
Description The beginning date of the date range for which to retrieve the rate changes that have occurred.
EndDate DateTime Optional
Description The end date of the date range for which to retrieve the rate changes that have occurred.

Returned Parameters

Name Data Type
RATE_ID Long
Description The ID of the unit’s rates record.
UNIT_ID Long
Description The unit’s ID number. This is maintained through rentals.
UNIT_NUMBER String
Description The unit’s number as assigned by the organization. This is not the UnitID.
SITE_ID Long
Description The site’s ID number.
SITE_NAME String
Description The site’s name as it appears in Store.
RENT_RATE Decimal
Description The current rent rate for the unit.
RENT_RATE_DATE DateTime
Description The date the rent rate was changed to it’s current amount.
STREET_RATE Decimal
Description The current street rate for the unit.
STREET_RATE_DATE DateTime
Description The date the street rate was change to it’s current amount.
PROFORMA_RATE Decimal
Description The current proforma rate for the unit.
PROFORMA_RATE_DATE DateTime
Description The date the proforma rate was changed to it’s current amount.
RACK_RATE Decimal
Description The current rack rate for the unit.
RACK_RATE_DATE DateTime
Description The date the rack rate was changed to it’s current amount.
RACK_TYPE_NUM Integer
Description The numerical value for the rack type.
RACK_TYPE_VAL String
Description The textual value for the rack type.
FUTURE_RATE Decimal
Description The rent rate to which the unit will change.
FUTURE_RATE_DATE DateTime
Description The date the future rate will take affect.
VERSION Integer
Description The unit’s version number which serves to prevent duplicate use of the unit.
CREATED_DATE DateTime
Description The date the rate record was originally created.
CREATED_BY_ID Long
Description The user’s ID that originally created the rate record.
CREATED_BY_NAME String
Description The first and last name of the user that originally created the rate record.
UPDATED_DATE DateTime
Description The date the rate record was most recently updated.
UPDATED_BY_ID Long
Description The user’s ID that most recently updated the rate record.
UPDATED_BY_NAME String
Description The first and last name of the user that last updated the rate record.
ORG_ID Long
Description The organization’s ID number.

Example

We’ll assume you’ve got a web reference, let’s name it BulkData, in your Visual Studio project. At this point we need to our objects. We’ll need the standard service object, a user request object and a data request object. We can define and create those like this:

// Create request and response objects
BulkData.LookupUser_Request user_request = new BulkData.LookupUser_Request();
BulkData.BulkDataSoapClient service = new BulkData.BulkDataSoapClient();
BulkData.BulkData_Request request = new BulkData.BulkData_Request();

Here’s my sample code of the Request and user objects.

// request
user_request.Username = "user";
user_request.Password = "pass";
user_request.Channel = 999;

request.OrgID = 123546;
request.BeginDate = DateTime.Today.AddDays(-1);
request.BeginDate = DateTime.Today;

Finally we can call the method and pass across the login object and the request object to retrieve our data. It’s a good idea to do this in a Try Catch block.

// Call the method that will load the response object
try
{
  BulkData.BulkRates_Response response;
  response = service.GetBulkRates(user_request, request);
}
catch (Exception ex)
{
  MessageBox.Show(ex.Message);
}

Note that if something goes wrong the service will respond with an exception. You’ll want to take a look at that message returned in that exception so it can be debugged.

For a full list of methods, see BulkData Methods.

Categories: API General, Rates/Pricing

Workflow for Creating a Reservation or Rental

November 21, 2016 Leave a comment

Entities

The following is a flow chart of the main entities involved in creating a rental or reservation in SWS.

swsworkflowexample

An account can have multiple contacts and multiple rentals. A rental must have a primary contact (Contact Type = ACCOUNT_MANAGER) and can have additional secondary contacts. Site rules may require at least one secondary contact as well. A contact that is primary on one rental may be primary, secondary or not related at all to another rental on the account. The account name for personal accounts is the last name, first name of the first contact added to the account. For business accounts an account name should be specified. Each rental will be associated with the unit being rented. The unit has a number assigned by the organization and a primary key known as the UnitID. The two are often confused. If you are displaying information to a tenant you will generally want to use the Unit Number. If you are renting or adjusting a unit in code the unit ID, as the item’s primary key, is generally required.

Finding A Unit and Dynamic Pricing

The first step is displaying the available units. There are multiple options for this: GetSiteUnitData, GetSiteUnitDataV2GetSiteUnitDataV3, GetUnitData and GetUnitDataWithPromos. GetUnitData returns ALL units in a site along with their pertinent information including ID’s and its version number which will be important when reserving the unit. This method allows a site to customize grouping, pricing and promos to their specifications. It means a little more work, but things will come out exactly how the organization prefers. The only required parameter is the SiteID, the rest of the parameters allow for filtering the results and are all optional. The GetSiteUnitData methods return a single unit based on a pre-set grouping. This grouping takes Width, Depth, Door, Climate, Access Type and Features values into account. For example, if you have ten 5X5 units, half that are climate controlled and half not, you will receive back, IF available, two units, one with climate control and one without. You also have the option to include the best available promotion for each item selected. Again, SiteID is the only required field. There are fewer filter options on this as the items have already been winnowed down. Also failing to indicate a desire for promos will default to false for performance purposes. Both methods return the information necessary to complete a reservation/create a new rental using the MakeReservation method.

Choosing an Account

For a brand new tenant, call CreateNewAccount. This method will create the account and at least one new contact, one new address and one new phone, which will then be available to accept rentals.

If you wish to add a unit to an existing customer’s account, you will need to use the SearchBy method to retrieve their AccountID and then use the AccountID to add the rental to their account.

Making a Reservation/Creating a New Rental

Once you have either created a new account or located an existing account, you can create a reservation/rental. First some terminology regarding reservations and rentals:

  • Quote Only – This is created when a person has indicated interest in renting a unit but does not wish to commit to a reservation or rental. An account is still required. This allows for obtaining all the contact information. A unit is still required so anyone following up on the potential sale is aware of what type of rental the customer is looking for. The unit is NOT put on hold and can be rented at anytime by anyone else.
  • Soft ReservationThis does not hold a specific unit, but will hold a unit of this type. The reservation will exist until its expiration date or until the reservation is cancelled. If there is only one unit left, it will not show as available to rent due to the soft reservation.
  • Hard Reservation This method holds a specific unit for a site specified length of time. Generally there is also a reservation deposit amount paid, although it is not required. If there is a deposit required, the payment process described below MUST be completed before the reservation process is considered complete. If it is not the rental will be cancelled during our nightly processing.
  • Rental – To heck with reservations, the customer has a moving van parked out front. The move in is NOT done, however, until the payment process below has been completed.

MakeReservation does all of the above including upgrading from one status to another. MakeReservation will always return a QuoteID. If a reservation or rental is created there will also be a RentalID returned.

Making a Payment

So you’ve created the account and we’ve made our unit selection now we have to pay for the thing. Making a payment is a three step process.

Step OneGetAssessments – This method retrieves a list of line items to be paid. Regardless if this is a new or existing rental and whether or not you already know the total due this method MUST be called. Assessments may or may not be in existence for the rental. By calling this method it will create any assessments the organization or site requires. Failing to call this process means you may not have the correct total due and will cause errors in payment.

The method will return a list of line items that are due for the requested time-frame. If the tenant has any cash credit/escrow that can be used for payment, they will also be listed here. Note: Cash credit/escrow is not automatically deducted from the total due.

Step TwoGetTotalDue – This step can be skipped if the items in GetAssessments are looped through and totaled. There are some rules to keep in mind for this option. Extended is the total due not including taxes for the assessment, a fulfilled amount indicates some payment has been made on the assessment and that will not be deducted from extended, finally any tax amount must be added in. If a cash credit/escrow is present the extended amount indicates the available balance that can be used toward payment.

Step ThreeMakePayment – And you thought we’d never get here. MakePayment accepts the above data, some total data and three payment types. One or any combination of payment types is allowed (i.e., customer wishes to pay half cash, half on a card, or possibly split the payment between two cards, etc.).

But, wait?! They have a promotion for the first month free and GetTotalDue says $0 is due. I don’t have to make a payment…. Yes, you do!!! Any new rental is not moved in until a payment is made. This will push the paid thru date forward and move the tenant in. If no payment is made, even if it’s a $0 cash payment, the rental will be ended as an abandoned rental during nightly processing. They will have to be moved in again, possibly missing out on a day of rent.

The MakePayment method will return a transaction ID if successful. The CashCreditApplied field has been deprecated.

SWS2 UpdatePushStreetRate Method

Allows you to do a bulk update on the street or push rates for a group of units at a site. The method allows for a collection of the PushStreetRateInfo object to be passed in. The return object is a comma delimited string of “Succeeded” or “Failed”. Due to a 4,000 character limitation, the unit_ids in the array are parsed into groupings less than 4,000 characters and each group returns a result of “Succeeded” or “Failed” for the batch appended to the return object. Each PushStreetRateInfo object’s array is parsed into their own groups and appended to the return object for the entire method.

Parameters

Name Data Type Is Required
NewRate Decimal Required
Description The dollar amount to which the rate will change.
RateType Integer Required
Description Indicates if it is the street rate (“1”) or the push rate (“2”) that is being updated.
UnitIDs Long (or an array of long) Required
Description The unit’s ID number for which the rate is being updated. This is returned when you use any of the GetSiteUnitData
calls and is maintained through rentals.
SiteID Long Required
Description The site’s ID number. This can be found using the GetSiteList method.

Returned Parameters

Name Data Type
UnitIDs Long (or an array of long)
Description The list of unit IDs where the street or push rate was updated.

Example

We’ll assume you’ve got a web reference, let’s name it Store, in your Visual Studio project. At this point we need to reference our objects. We’ll need the standard service object, a UpdatePushStreetRate_Request request object and a PushStreetRateInfo object. We can define and create those like this:

// Create a request and response objects
StoreServiceClient client = new StoreServiceClient();
UpdatePushStreetRate_Request request = new UpdatePushStreetRate_Request();
PushStreetRateInfo rateInfo = new PushStreetRateInfo();

As with every method we need to pass in credentials. We also set up the parameters for our request.

client.ChannelFactory.Credentials.UserName.UserName = "user";
client.ChannelFactory.Credentials.UserName.Password = "pass";
client.ChannelFactory.Credentials.SupportInteractive = true;

rateInfo.UnitIDs = new long[] { 123456, 456789 };
rateInfo.RateType = 1;
rateInfo.NewRate = 50m;

request.SiteID = 123456;
request.PushStreetRateInfo = new PushStreetRateInfo[] { rateInfo };

Finally we can call the method and pass across the login object and the request object to update the rate/s. It’s a good idea to do this in a Try Catch block.

try
{
    // Call the method that will load the response object
    UpdatePushStreetRate_Response resp;
    resp = client.UpdatePushStreetRate(request);
}
catch (Exception ex)
{
    MessageBox.Show(ex.Message);
}

Note that if something goes wrong the service will respond with an exception. You’ll want to take a look at that message returned in that exception so it can be debugged.

For a full list of methods see SWS2 Methods.

Categories: API General, Rates/Pricing

SWS UpdateRentRateV2 Method

October 13, 2015 Leave a comment

Lets you change the rent rate for a unit. Multiple units can be individually processed with a new rate. Letters can also be scheduled to be sent when updating the rent rates on active rentals. This method allows you to choose if the letter will be centralized mail or local mail.

Parameters

Name DataType Is Required
AcctID Long Optional
Description The account’s ID number. This is returned when you use the CreateNewAccount method or can be retrieved with the SearchBy method. Only required when sending a letter.
EffectiveDate DateTime Required
Description The date the future rate will go into effect.
LetterDate DateTime Optional
Description The date the letter is to be sent. Only required when SendLetter is “True”.
NewRate Decimal Required
Description The new rent rate for the rental item.
OrgID Long Required
Description The organization’s ID number.
RentalID Long Optional
Description The rental item’s ID number. This is returned when using the MakeReservation method or can be searched for using the SearchBy method. Only required if SendLetter is “True”.
SendLetter Boolean Optional
Description Indicates if the system is to generate a rate change letter (“True”) or not (“False”).
SiteID Long Required
Description The site’s ID number. This can be found using the GetSiteList method.
UnitID Long Required
Description This is returned when you use any of the GetSiteUnitData calls.
UnitVersion Decimal Required
Description The unit’s version number which serves to prevent duplicate use of the unit.
MailLocal Boolean Required
Description Indicates if the letter should be printed and mailed through the site (“True”) or through centralized mailing (“False”).

Returned Parameters

Name DataType
ErrorMessage String
Description If “Succeeded” is “False” this will give additional information as to what failed.
Succeeded Boolean
Description Indicates if the rate change was completed successfully (“True”) of not (“False”).
UnitID Long
Description The unit’s ID number where the rate was updated. This is maintained through rentals.

Example

As with every method we need to pass in credentials. We do this with the LookupUser request object.

We will assume you have a web reference, let us name it SWS, in your Visual Studio project. At this point we need to define our objects.  We will need the standard service object, an UpdateRentRateV2 request object, and an UpdateRentRateV2 response object. We will also need a RentRateReqDataV2 array we can pass to the request. We can define and create those like this:

// Create a request and response objects
SWS.WSSoapClient service = new SWS.WSSoapClient();
SWS.UpdateRentRateV2_Request request = new SWS.UpdateRentRateV2_Request();
SWS.UpdateRentRateV2_Response response;

SWS.RentRateReqDataV2[] reqRentRate = new SWS.RentRateReqDataV2[1];

Here is a sample code of the request object:

// UpdateRentRate Request
reqRentRate[0].OrgID = 123456;
reqRentRate[0].SiteID = 123456;
reqRentRate[0].AcctId = 123456;
reqRentRate[0].UnitID = 123456;
reqRentRate[0].UnitVersion = 23;
reqRentRate[0].RentalId = 123456;
reqRentRate[0].NewRate = 55.25m;
reqRentRate[0].EffectiveDate = new DateTime(2017, 9,1);
reqRentRate[0].SendLetter = true;
reqRentRate[0].MailLocal = true;
reqRentRate[0].LetterDate = new DateTime(2017, 8, 1);

Finally we can call the method and pass across the login object and the request object to retrieve our requested information. It’s a good idea to do this in a Try Catch block.

// Call the method that will load the response object
try
{
  response = service.UpdateRentRateV2(user_request, request);
}
catch (Exception ex)
{
  MessageBox.Show(ex.Message);
}

Note that if something goes wrong the service will respond with an exception. You will want to capture the message in the exception so it can be debugged.

For a full list of methods see SWS Methods.

Categories: API General, Rates/Pricing