Overview
This API allows you to retrieve the product rate for a given service, product, date and quantity.
Business Rules
This API call will retrieve rates set at on a Product Rate Override or on a Product Rate Card, either a specific rate, a category or subcategory mark-up, or an overall product rate card mark-up.
- If a product rate override is set, the price on the product rate card will also be shown (if set) so it's transparent as to what the rate would be, if the override didn't exist (see Example B in the API response examples).
- If a mark-up is set either on the Product Category, Product Sub Category, or an overall mark-up on the Product Rate Card, the API response will be presented in the same way. Information regarding the specific source of the mark-up within Product Rate Card is not returned in this API Call (See Example C,D and E).
- If a rate is set on an Emersion Price Book or a Product Rate Card attached to an Account Discount Subscription, this API call will not return this information. The response will indicate no rate exists.
SOAP Example
API Call
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:emersion:api">
<soapenv:Header/>
<soapenv:Body>
<urn:GetProductRate>
<urn:ServiceID>1235051</urn:ServiceID>
<urn:ProductID>2022965</urn:ProductID>
<urn:Date>2020-10-01T00:00:00+10:00</urn:Date>
<urn:Quantity>-99</urn:Quantity>
</urn:GetProductRate>
</soapenv:Body>
</soapenv:Envelope>
Example A: API Response - Specific Rate on Rate Card
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:emersion:api" xmlns:ns2="urn:emersion:types">
<SOAP-ENV:Body>
<ns1:GetProductRateResponse>
<ns1:ServiceSubscription ID="3891606">
<ns1:ServicePlan ID="206621">Electricity Service</ns1:ServicePlan>
</ns1:ServiceSubscription>
<ns1:ProductRateCard ID="120132">
<ns1:Name>Electricity PRC</ns1:Name>
<ns1:ProductRateID>273656</ns1:ProductRateID>
<ns1:Price>
<ns2:Amount>.0012</ns2:Amount>
<ns2:TaxType ID="5" Percentage="15">New Zealand GST</ns2:TaxType>
</ns1:Price>
</ns1:ProductRateCard>
</ns1:GetProductRateResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example B: API Response - Product Rate Override on Subscription
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:emersion:api" xmlns:ns2="urn:emersion:types">
<SOAP-ENV:Body>
<ns1:GetProductRateResponse>
<ns1:ServiceSubscription ID="3891606">
<ns1:ServicePlan ID="206621">Electricity Service</ns1:ServicePlan>
</ns1:ServiceSubscription>
<ns1:ProductRateCard ID="120132">
<ns1:Name>Electricity PRC</ns1:Name>
<ns1:ProductRateID>273656</ns1:ProductRateID>
<ns1:Price>
<ns2:Amount>.0012</ns2:Amount>
<ns2:TaxType ID="5" Percentage="15">New Zealand GST</ns2:TaxType>
</ns1:Price>
</ns1:ProductRateCard>
<ns1:ProductRateOverride ID="127918">
<ns1:Markup>
<ns2:Percentage>-10</ns2:Percentage>
</ns1:Markup>
</ns1:ProductRateOverride>
</ns1:GetProductRateResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example C: Markup set on Product Category
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:emersion:api" xmlns:ns2="urn:emersion:types">
<SOAP-ENV:Body>
<ns1:GetProductRateResponse>
<ns1:ServiceSubscription ID="3891606">
<ns1:ServicePlan ID="206621">Electricity Service</ns1:ServicePlan>
</ns1:ServiceSubscription>
<ns1:ProductRateCard ID="120132">
<ns1:Name>Electricity PRC</ns1:Name>
<ns1:Markup>
<ns2:Percentage>9</ns2:Percentage>
</ns1:Markup>
</ns1:ProductRateCard>
</ns1:GetProductRateResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example D: Markup set on Product Sub Category
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:emersion:api" xmlns:ns2="urn:emersion:types">
<SOAP-ENV:Body>
<ns1:GetProductRateResponse>
<ns1:ServiceSubscription ID="3891606">
<ns1:ServicePlan ID="206621">Electricity Service</ns1:ServicePlan>
</ns1:ServiceSubscription>
<ns1:ProductRateCard ID="120132">
<ns1:Name>Electricity PRC</ns1:Name>
<ns1:Markup>
<ns2:Percentage>13</ns2:Percentage>
</ns1:Markup>
</ns1:ProductRateCard>
</ns1:GetProductRateResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example E: Overall Markup on Product Rate Card
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:emersion:api" xmlns:ns2="urn:emersion:types">
<SOAP-ENV:Body>
<ns1:GetProductRateResponse>
<ns1:ServiceSubscription ID="3891606">
<ns1:ServicePlan ID="206621">Electricity Service</ns1:ServicePlan>
</ns1:ServiceSubscription>
<ns1:ProductRateCard ID="120132">
<ns1:Name>Electricity PRC</ns1:Name>
<ns1:Markup>
<ns2:Percentage>-100</ns2:Percentage>
</ns1:Markup>
</ns1:ProductRateCard>
</ns1:GetProductRateResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Field Descriptions
All field names are case sensitive. Check enumerated values in the descriptions to confirm capitalisation and spacing. See field types for additional information..
| Name | Description | Required? | Field Type | Character limit | Values |
|---|---|---|---|---|---|
ServiceID | Emersion Service for the rate check. | Yes | Int | 1235051 | |
ProductID | Product for the rate check. | Yes | Int | 2022965 | |
Date | Date at which the rate was applicable. | Yes | XML Compatible date format | 2020-10-01T00:00:00+10:00 | |
| Quantity | Quantity that the rate applies to. | Yes | Int | 1 |
Error Handling
| Error Message | Description |
|---|---|
| Invalid ServiceID | You have either entered an invalid service ID, or the service ID does not belong to the calling account. |
| Invalid ProductID | You have entered an invalid Product ID |
| Could not find a Subscription for a given ServiceID and Date | The date entered may be prior to the subscription start date, or after the subscription end date. Alternatively, the subscription may be in a preactive state. |
| Invalid Date | You have entered an invalid date string. |
| Invalid Quantity | You have entered an invalid string into the quantity field (check for letters and other special characters such as n and m-dash). |
| Could not find a Product Rate Card for arguments provided |