# Agreements An **agreement** is a collection of rates and terms that define what a *customer* will be charged and a *provider* will bill for services provided. An **agreement** can be attached to *services*, *opportunities*, *schedules*, or *reservations*. When a *customer* makes a new request, the Octoo application will attempt to auto-bind the customer's *in effect* agreement to the services (and schedules) of the request. The same is true for when a provider *expresses interest* in a service: an in-effect agreement should be automatically attached. Reservations also use agreements. If a particular request requires unique rates or terms, a partner can modify that request's *one-off* agreement. These new rates/terms will only apply to that request. A *one-off* agreement can be labeled and re-used if it is needed. The customer service (or provider job) always gets its rates and terms from the attached agreement. ### Features * Zone based * Minimum in minutes * Floor in minutes * Mileage rate types (e.g., "Federal") * Auto-binding vs one-off * Pay schedules (e.g., office hours and after hours) * Base service rates * Add-on rates (e.g., holiday, legal) * Time-based policies (e.g., cancellation or short notice) * Slip policies (e.g., mileage, tolls, parking, travel, prep) ### A zone is a collection of compatible agreements A *zone* is a service area defined by a partner that contains a collection of providers and customers with compatible rates and terms. When services are added to a request, Octoo automatically searches for a compatible zone via the partner's *zone lookup*. This is a table that describes which zones apply to which locations and modalities (e.g, in-person or remote). The lookup is defined at a state, county, or city level. A default zone will be applied if there isn't a specific match. An **agreement** will be bound to a service/opportunity based on a matching *zone*. For example: if Customer A and Provider B have agreements in "Zone: NYC" we would expect both agreements to be (mostly) compatible in terms of slip, cancellation, short notice, and other policies and features of the agreements. That is: Provider B should be able to work for Customer A. If Customer C has an agreement in "Zone Washington State" we wouldn’t consider Provider B because the rates/terms are too different between the two zones (e.g., appearance fees, minimums, booking charges, etc are different in Washington than the Bay Area). So that’s generally the concept of a zone: *collection of compatible rates/terms between customers and providers.* ### Auto-binding vs one-off An **auto-bindable** agreement is the one that our system will automatically attach to new services/opportunities in the same **zone** and for the appropriate provider types. An *auto-bindable* agreement has an *in effect* date and only one can exist for a particular *zone*. If a partner attempts to create overlaping or conflicting auto-bindable agreements the system will raise an error. A **one-off** (manually assigned) agreement is on that a partner administrator can manually assign to a service/opportunity as needed (we call it **one-off** but it is re-usable). For example, Customer A allows providers to charge prep time—but only for certain requests. We would create a second agreement (called: "Customer A w/Prep Time") and make the required changes to this agreement to reflect prep time. This second agreement would **not** be *auto-bindable*. As needed, admins could swap the travel time agreement into a service. A customer or provider can only have **one** auto-bindable agreement for a given criteria. This way our system always knows which one to bind based on the date of the service. ### Minimum **floor** in minutes This is a little counter intuitive but it works in the same as the `minimum_in_minutes` only by setting a floor. For example, if the `minimum_floor_in_minutes = 60` (most common) this means the provider will not have any service slips for a job that is less than one hour long. It makes sense to be used in conjunction with another slip policy (e.g., in the case a 1.5 hour appearance fee charge). So if a provider works for only 30 minutes they would not bill any service slips (they would just get the "appearance fee" slip, from the example above). If they worked for 1.5 hours then would bill for 0.5 hours of service slips. ### Base Service Rate The **base service rate** is the primary rate charged for the services provided. Most **partners** will utilize only one **base service rate**; however, you can specific more than one (e.g., "regular" and "recurring"). Regardless, on **base service rate** must be set as the *default* rate. ### Add-On Rate An add-on rate "adds" to the base service rate. You can stack them. Services and opportunities have add-on rates *applied* to them based on criteria (e.g., holidays or corresponding with certain qualifications). An add-on rate can be waived (service-level or opportunity-level). If a provider agreement or customer agreement *does not support* the add-on rate it will *still be applied*. So a "holiday" will always appear tagged on the service/opportunity a "holiday add-on rate" even if there is no change to what the customer/provider is being charged. ### Time-based Policy A time-based policy is applied via one of three different methods: flat rate, pay schedule, or percentage. 1. **FLAT RATE**: a new slip is added to the **proforma** invoice for the flat rate amount. If a flat rate policy is *waived* a second slip will be added to reverse the charge. When a cancellation policy is flat rate *no additional service slips are added* (the flat rate takes the place of the service slips). A short notice flat rate is added *in adddition* to the regular service slips. 2. **PERCENTAGE**: \[CANCELLATION ONLY] applies a *discount* to each service slip on the proforma invoice. This discount reflects the percentage of the policy. If the policy is 100% no discount is applied and each service slip is charged in full. If the cancellation policy is set to be 50% then the service slips would be discounted by 50%. NOTE: we currently do *not* support short notice percentage based policies. 3. **RATE TABLE (Add-On)**: \[SHORT NOTICY ONLY] the rate table is consulted for this policy and is treated like an "add-on" rate increasing the serivce slip total. NOTE: we currently do not support cancellation rate table based policies. When a service/opportunity is created or cancelled time-based policies are automatically applied. They can also be waived. Unlike an add-on rate, a time-based policy is *not* applied unless the agreement calls for it. ### Pay Schedule Each account defines their own **pay schedule** (and there can be more than one). For example, perhaps an account has one "default" pay schedule that includes "weekday, "weeknight", and "weekend" rates. They may have a second **pay schedule** that only defines "office hours" and "after hours" rates. ### Slip Policies A **slip policy** defines how certain **slips** on the **proforma** invoices will be handles. Both provider agreements and customer agreements define their own slip policies and they can be contigent on one another. The following **slip types** can have policies: mileage, parking, tolls, travel time, prep time, booking charges, appearance fees. The policy can also have a *term* that restricts its usage. A policy can have a *minimum*, a *maximum*, a *floor*, and a *fixed* amount. For example, here are some possible combinations: * "Mileage - unrestricted" * "Mileage - maximum of 100 miles" (cannot bill over 100) * "Mileage - floor of 40 miles" (starts billing only after reaching 40 miles) * "Booking charge - $30 flat rate" A **slip policy** can also be *contingent* on the other party's policy. For example, the provider's agreement may have a "Mileage policy - contingent on customer". This means that if the customer supports paying for the mileage the provider can bill for it. However, if the customer does not, the provider cannot. If a **slip policy** is *not* contingent that means the provider/customer will always have it applied to their invoices. #### One-way billing A **slip policy** can have *one-way billing*. This means that the policy will *not* be shared between customer and provider. For example, a customer may have an internal policy that does not allow mileage to be included on their invoices. The one-way billing feature allow partners to circumvent it by paying providers the milage directly (one-way) without billing the customer. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.octoo.com/general/agreements.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.