How to read an order for Service Department
This document is designed to help you understand how you can read a Repair Order for the Service Department. The returned order will contain all the relevant order information. To use this endpoint, you first need your credentials. If you don't already have them, head over to the Authentication and Authorization page to see how you can request credentials from us.
Parameters Used
Path parameters
Parameter Name | Value | Description | Required |
---|---|---|---|
departmentUUID | String | Unique identifier of dealer department | Yes |
orderUUID | String | Unique identifier of dealer order | Yes |
Authorization
Parameter Name | Description | Required |
---|---|---|
{{basic_auth_token}} | Authorization: Base64 encoded string using Service Subscriber Username and password | Yes |
Scope
This request requires the following authorization scopes:
Scope | Level | Description |
---|---|---|
order.fetch | DealerDepartment | Authorizes client to read service order for provided user's dealer department |
Endpoint
curl -X GET "https://api.mykaarma.com/order/v2/department/{{departmentUUID}}/global_order/{{orderUUID}}"
-H "authorization: {{basic_auth_token}}"
Response
{
"statusCode":"string",
"orderReadChecksum":"string",
"errors":[
],
"warnings":[
],
"order":{
"uuid":"string",
"order":{
"type":"RO",
"header":{
"orderNumber":"string",
"serviceAccount":"string",
"accountingAccount":"string",
"dmsStatus":"string",
"status":"string",
"deptType":"string",
"advisorNumber":"string",
"advisorName":"string",
"dealerAssociateUuid":"string",
"originalAssociateUUID":"string",
"appointmentNumber":"string",
"tagNumber":"string",
"mileageIn":"string",
"mileageOut":"string",
"orderDate":"string",
"orderTime":"string",
"promisedDate":"string",
"promisedTime":"string",
"voidDate":"string",
"closeDate":"string",
"closeTime":"string",
"waiter":"string",
"rental":"string",
"soldHours":"string",
"actualHours":"string",
"laborCost":"string",
"laborSale":"string",
"laborSaleCustomer":"string",
"laborSaleInternal":"string",
"laborSaleWarranty":"string",
"partsCost":"string",
"partsCostCustomer":"string",
"partsCostInternal":"string",
"partsCostWarranty":"string",
"partsSale":"string",
"partsSaleCustomer":"string",
"partsSaleInternal":"string",
"partsSaleWarranty":"string",
"lubeSale":"string",
"lubeSaleCustomer":"string",
"lubeSaleInternal":"string",
"lubeSaleWarranty":"string",
"miscSale":"string",
"miscSaleCustomer":"string",
"miscSaleInternal":"string",
"miscSaleWarranty":"string",
"subletSale":"string",
"subletSaleCustomer":"string",
"subletSaleInternal":"string",
"subletSaleWarranty":"string",
"customerPayAmount":"string",
"customerPayStateTax":"string",
"warrantyPayStateTax":"string",
"internalPayStateTax":"string",
"internalPayAmount":"string",
"warrantyPayAmount":"string",
"invoiceURL":"string",
"payTypes":"string",
"description":"string",
"printDate":"string",
"printTime":"string",
"deliveryAmount":"string",
"estimate":"string",
"localTaxAmountCustomer":"string",
"localTaxAmountWarranty":"string",
"localTaxAmountInternal":"string",
"stockNumber":"string",
"isInternal":"string",
"isVoided":"string",
"invoiceTotal":"string",
"mykCreatedDate":"string"
},
"vehicle":{
"uuid":"string",
"vin":"string",
"make":"string",
"key":"string",
"model":"string",
"color":"string",
"licensePlate":"string"
},
"customer":{
"uuid":"string",
"key":"string",
"firstName":"string",
"lastName":"string"
},
"jobs":[
{
"jobIdentifier":"string",
"jobNumberString":"string",
"lopSeqNumber":"string",
"laborOpCode":"string",
"laborOpCodeDesc":"string",
"laborType":"string",
"laborSale":"string",
"soldHours":"string",
"actualHours":"string",
"partsSale":"string",
"miscSale":"string",
"bookerNo":"string",
"dispatchLineStatus":"string",
"techNo":"string",
"campaignCode":"string",
"estimates":{
"laborEstimate":"string",
"partsEstimate":"string",
"serviceEstimate":"string",
"taxEstimate":"string",
"lubeEstimate":"string",
"miscEstimate":"string",
"subletEstimate":"string"
},
"parts":[
{
"partNumber":"string",
"description":"string",
"seqNo":"string",
"quantityOrdered":"string",
"quantitySold":"string",
"cost":"string",
"salePrice":"string",
"saleTotal":"string",
"laborType":"string"
}
],
"gog":[
{
"itemType":"string",
"itemDescription":"string",
"jobNumber":"string",
"quantity":"string",
"saleTotal":"string",
"salePrice":"string",
"laborType":"string"
}
],
"techHours":[
{
"techNo":"string",
"partSeqNo":"string",
"laborCost":"string",
"laborSale":"string",
"soldHours":"string",
"otherHours":"string",
"laborType":"string"
}
],
"comments":[
{
"comment":"string",
"lastUpdatedBy":"string",
"updateDate":"string",
"updateTime":"string"
}
],
"ccc":{
"complaint":"string",
"complaintCode":"string",
"cause":"string",
"correction":"string"
}
}
],
"mls":[
{
"laborType":"string",
"opCode":"string",
"opCodeDesc":"string",
"failureCode":"string",
"salePrice":"string",
"costPrice":"string",
"saleCompany":"string",
"sourceCompany":"string",
"lineCode":"string",
"poNumber":"string",
"poCreateDate":"string",
"poLineID":"string",
"mlsType":"string"
}
]
}
}
}
Response Object Explanation
Parameter Name | Description | |
---|---|---|
orderReadChecksum | The orderReadChecksum is a unique identifier used to verify the integrity and consistency of the order data retrieved from myKaarma. It should be included in follow-up update requests to ensure that the order data being modified is current and has not been altered since it was last read. |
Parameter Name | Description | |
---|---|---|
uuid | unique identifier of Order in mykaarma. |
Order Details
Parameter Name | Description |
---|---|
uuid | unique identifier of Order in mykaarma. |
type | "RO" for service/repair order |
orderNumber | Unique identifier for the order. Ordernumber should match regex ^[a-zA-Z0-9-#_\s]*$ |
serviceAccount | Account associated with the service. |
accountingAccount | Account used for accounting purposes. |
status | Current status of the order in myKaarma. Possible values O/P/C signifying OPENED , PRE-INVOICED, CLOSED |
dmsStatus | Current status of the order in the DMS. Possible values O/P/C signifying OPENED , PRE-INVOICED, CLOSED. Check the documentation here for difference between this field and the status field above |
deptType | Type of department handling the order. |
advisorNumber | Identifier for the service advisor in the DMS to which RO is being assigned . |
advisorName | Name of the service advisor. |
dealerAssociateUuid | Unique token issued by mykaarma of the dealer associate to which RO is being assigned |
originalAssociateUUID | Unique token issued by mykaarma of the dealer associate which is creating the RO. |
appointmentNumber | Appointment Number (generated in the DMS) associated with RO . |
tagNumber | Identifier for the vehicle tag. |
mileageIn | Mileage of the vehicle when it arrived. |
mileageOut | Mileage of the vehicle when it left. |
orderDate | Date when the order was created. yyyy-MM-dd format in PST timezone |
orderTime | Time when the order was created. HH:mm:ss in PST timezone |
printDate | The date when the repair order was printed, formatted as yyyy-MM-dd in the PST timezone |
printTime | The time when the repair order was printed, formatted as HH:mm:ss in the PST timezone. |
promisedDate | Date by which the service is promised to be completed. yyyy-MM-dd format in PST timezone |
promisedTime | Time by which the service is promised to be completed. HH:mm:ss format in PST timezone |
voidDate | Date when the order was voided. yyyy-MM-dd HH:mm:ss format in PST timezone |
closeDate | Date when the order was closed. yyyy-MM-dd format in PST timezone |
closeTime | Time when the order was closed. HH:mm:ss format |
waiter | Indicates if the customer is waiting for the service. "Y/N" |
rental | Indicates if a rental vehicle is provided. "Y/N" |
soldHours | Number of hours sold for the service. |
actualHours | Actual hours spent on the service. |
laborCost | Cost of labor for the service. (Only numerics alowed upto 2 decimal places like "12.56" ) |
laborSale | Sale amount for labor. (Only numerics alowed upto 2 decimal places like "12.56" ) |
laborSaleCustomer | Sale amount for labor charged to the customer. (Only numerics alowed upto 2 decimal places like "12.56" ) |
laborSaleInternal | Sale amount for internal labor. (Only numerics alowed upto 2 decimal places like "12.56" ) |
laborSaleWarranty | Sale amount for labor under warranty. (Only numerics alowed upto 2 decimal places like "12.56" ) |
partsCost | Cost of parts used in the service. (Only numerics alowed upto 2 decimal places like "12.56" ) |
partsCostCustomer | Cost of parts charged to the customer. (Only numerics alowed upto 2 decimal places like "12.56" ) |
partsCostInternal | Cost of parts for internal use. (Only numerics alowed upto 2 decimal places like "12.56" ) |
partsCostWarranty | Cost of parts under warranty. (Only numerics alowed upto 2 decimal places like "12.56" ) |
partsSale | Sale amount for parts. (Only numerics alowed upto 2 decimal places like "12.56" ) |
partsSaleCustomer | Sale amount for parts charged to the customer. (Only numerics alowed upto 2 decimal places like "12.56" ) |
partsSaleInternal | Sale amount for internal parts. (Only numerics alowed upto 2 decimal places like "12.56" ) |
partsSaleWarranty | Sale amount for parts under warranty. (Only numerics alowed upto 2 decimal places like "12.56" ) |
lubeSale | Sale amount for lubricants. (Only numerics alowed upto 2 decimal places like "12.56" ) |
lubeSaleCustomer | Sale amount for lubricants charged to the customer. (Only numerics alowed upto 2 decimal places like "12.56" ) |
lubeSaleInternal | Sale amount for internal lubricants. (Only numerics alowed upto 2 decimal places like "12.56" ) |
lubeSaleWarranty | Sale amount for lubricants under warranty. (Only numerics alowed upto 2 decimal places like "12.56" ) |
miscSale | Sale amount for miscellaneous items. (Only numerics alowed upto 2 decimal places like "12.56" ) |
miscSaleCustomer | Sale amount for miscellaneous items charged to the customer. (Only numerics alowed upto 2 decimal places like "12.56" ) |
miscSaleInternal | Sale amount for internal miscellaneous items. (Only numerics alowed upto 2 decimal places like "12.56" ) |
miscSaleWarranty | Sale amount for miscellaneous items under warranty. (Only numerics alowed upto 2 decimal places like "12.56" ) |
subletSale | Sale amount for miscellaneous items under warranty. (Only numerics alowed upto 2 decimal places like "12.56" ) |
subletSaleCustomer | Sale amount for sublet services charged to the customer. (Only numerics alowed upto 2 decimal places like "12.56" ) |
subletSaleInternal | Sale amount for internal sublet services. (Only numerics alowed upto 2 decimal places like "12.56" ) |
subletSaleWarranty | Sale amount for sublet services under warranty. (Only numerics alowed upto 2 decimal places like "12.56" ) |
customerPayAmount | Total amount payable by the customer. (Only numerics alowed upto 2 decimal places like "12.56" ) |
customerPayStateTax | The state tax amount payable by the customer, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
warrantyPayStateTax | The state tax amount covered by the warranty, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
internalPayStateTax | The state tax amount covered by internal charges, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
localTaxAmountCustomer | The local tax amount payable by the customer, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
localTaxAmountWarranty | The local tax amount covered by the warranty, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
localTaxAmountInternal | The local tax amount covered by internal charges, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
isInternal | Indicates whether the repair order is for internal purposes, typically represented as a boolean value (e.g., "true" or "false"). |
isVoided | Indicates whether the repair order has been voided, typically represented as a boolean value (e.g., "true" or "false"). |
invoiceTotal | The total amount of the invoice, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
mykCreatedDate | The date when the order was created in myKaarma, formatted as yyyy-MM-dd. PST timezone |
stockNumber | The identifier for the vehicle's stock, typically used for inventory management. |
invoiceURL | The URL link to access the invoice associated with the repair order. |
payTypes | The different methods or categories of payment applicable to the repair order. |
estimate | Estimate of the order |
internalPayAmount | Total internal charges, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
warrantyPayAmount | Total amount covered by the warranty, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
description | Description of the order. |
Vehicle Information
Parameter Name | Description |
---|---|
vehicle.uuid | Unique identifier issued by mykaarma for the vehicle for which the order is being created. |
vehicle.vin | Vehicle Identification Number for the vehicle for which the order is being created . |
vehicle.make | Manufacturer of the vehicle the order is being created. |
vehicle.model | Model of the vehicle. |
vehicle.key | Model of the vehicle. |
vehicle.color | Model of the vehicle. |
vehicle.licensePlate | Model of the vehicle. |
Customer Information
Parameter Name | Description |
---|---|
customer.uuid | Unique identifier issued by mykaarma for the customer for which the order is being created. |
customer.firstName | First name of the customer. |
customer.lastName | Last name of the customer. |
customer.key | Unique identifier issued by mykaarma for the customer for which the order is being created. |
Job details
Parameter Name | Description |
---|---|
job.jobIdentifier | Unique identifier for the line + labor operation. Example "A-1","B-2" |
job.jobNumberString | Unique identifier for the line. Example "A","B","C" |
job.lopSeqNumber | Sequence number for the labor operation. Example "1","2" ,"3" |
job.laborOpCode | Code for the labor operation. Example "OIL" |
job.laborOpCodeDesc | Description of the labor operation. |
job.laborType | Type of labor performed. Perferred allowed values are C/W/I |
job.dmsLaborType | The type of labor performed as recorded in the Dealer Management System (DMS) |
job.serviceType | The type of service performed |
job.jobTotal | The total cost associated with a specific job, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
job.shopCharge | The charge associated with shop supplies or services, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
job.complaintCode | A code representing the type or category of the customer's complaint. |
job.addOnLine | Indicates additional labor or services added to the repair order, with preferred allowed values being Y/N |
job.partsFlag | |
job.dispatchEstimatedDuration | Type of labor performed. Perferred allowed values are C/W/I |
job.comeBackFlag | Indicates whether the repair order is a comeback, typically represented as a boolean value (e.g., "true" or "false")./ ("Y" , "N") |
job.laborSale | Sale amount for the labor.(Only numerics alowed upto 2 decimal places like "12.56" ) |
job.soldHours | Number of hours sold for the job. |
job.actualHours | Actual hours spent on the job. |
job.partsSale | Sale amount for parts used in the job. (Only numerics alowed upto 2 decimal places like "12.56" ) |
job.miscSale | Sale amount for miscellaneous items in the job. (Only numerics alowed upto 2 decimal places like "12.56" ) |
job.bookerNo | Booker number for the job. |
job.dispatchLineStatus | Status of the dispatch line. |
job.techNo | Identifier for the technician in the DMS who performed the job. |
job.campaignCode | Code for any applicable campaign. |
Estimate Information
Parameter Name | Description |
---|---|
estimate.laborEstimate | The estimated cost of labor for the job , formatted as a numeric value up to two decimal places (e.g., "12.56"). |
estimate.partsEstimate | The estimated cost of parts for the repair order, formatted as a numeric value up to two decimal places. |
estimate.serviceEstimate | The estimated cost of services for the repair order, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
estimate.taxEstimate | The estimated tax amount for the repair order, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
estimate.lubeEstimate | The estimated cost of lubricants for the repair order, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
estimate.miscEstimate | The estimated cost of miscellaneous items for the repair order, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
estimate.subletEstimate | The estimated cost of sublet services for the repair order, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
Parts Information
Parameter Name | Description |
---|---|
part.partNumber | Number identifying the part. |
part.description | Description of the part. |
part.seqNo | Sequence number for the part. |
part.quantityOrdered | Quantity of the part ordered. |
part.quantitySold | Quantity of the part sold. |
part.quantityShipped | Quantity of the part shipped. |
part.quantityAvailable | Quantity of the part available. |
part.listPrice | The manufacturer's suggested retail price (MSRP) for the part, formatted as a numeric value up to two decimal places (e.g., "12.56"). |
part.extendedSalePrice | The total sale amount for the part, calculated by multiplying the sale price by the quantity sold, formatted as a numeric value up to two decimal places. |
part.source | The origin or supplier of the part, indicating where it was obtained or purchased from. |
part.partSaleJournal | A record of the sales transactions for the part, typically used for tracking and accounting purposes. |
part.partSaleCompany | The company responsible for the sale of the part, typically used for accounting and inventory management purposes. |
part.specStatus | The status indicating the specifications or condition of the part, typically used for inventory management and tracking. |
part.partCoreAccount | An account used to track the core charge associated with the part, typically related to the return of a used part for credit. |
part.partSaleAccount | An account used to record the sales transactions of the part, typically for accounting and inventory management purposes. |
part.mcdPartsPercentage | The percentage of the part's cost that is covered under the manufacturer's core deposit program, typically represented as a numeric value. |
part.binNumber | The location identifier for the part within the inventory storage system, used for efficient tracking and retrieval. |
part.unitServiceCharge | The charge associated with the service provided for the part, typically formatted as a numeric value up to two decimal places (e.g., "12.56"). |
part.mfrCode | The manufacturer's code associated with the part, used for identification and tracking purposes. |
part.includesCoreFlag | Indicates whether the part includes a core charge, typically represented as a boolean value (e.g., "true" or "false"). |
part.cost | Cost of the part. |
part.salePrice | Sale price of the part. |
part.saleTotal | Total sale amount for the part. |
part.laborType | Type of labor associated with the part. |
GOG Information
Parameter Name | Description |
---|---|
gog.itemType | Type of item in the GOG. |
gog.itemDescription | Description of the item. |
gog.jobNumber | Job number associated with the item. |
gog.quantity | Quantity of the item. |
gog.saleTotal | Total sale amount for the item. |
gog.salePrice | Sale price of the item. |
gog.salePrice | Sale price of the item. |
gog.laborType | Type of labor associated with the item. |
Tech Hours
Parameter Name | Description |
---|---|
tech.techNo | Identifier for the technician in the DMS who performed the job. |
tech.techUuid | Identifier for the technician in the myKaarma who performed the job. |
tech.mcdLaborPercentage | The percentage of labor costs covered under the manufacturer's core deposit program, typically represented as a numeric value. |
tech.timeCardHours | The total hours recorded for the technician's work on the job, typically represented as a numeric value. |
tech.partSeqNo | Sequence number for the part, used to identify the order of parts in the repair order. |
tech.laborCost | Cost of labor for the technician. |
tech.laborSale | Sale amount for the labor. |
tech.soldHours | Number of hours sold for the technician's work. |
tech.otherHours | Additional hours associated with the technician's work. |
tech.laborType | Type of labor performed by the technician. |
Comments
Parameter Name | Description |
---|---|
comments.comment | Text of the comment. |
comments.lastUpdatedBy | Identifier for the person who last updated the comment. |
comments.updateDate | Date when the comment was last updated. yyyy-MM-dd format UTC timezone |
comments.updateTime | Time when the comment was last updated. HH:mm:ss format UTC timezone |
Complaint cause correction
Parameter Name | Description |
---|---|
ccc.complaint | Description of the customer's complaint. |
ccc.complaintCode | Code for the complaint. |
ccc.cause | Cause of the job. |
ccc.correction | Correction made to address the complaint. |
MLS Information
Parameter Name | Description |
---|---|
mls.laborType | Type of labor in the MLS. |
mls.opCode | Operation code in the MLS. |
mls.opCodeDesc | Description of the operation code. |
mls.failureCode | Code for any failure. |
mls.salePrice | Sale price in the MLS.. |
mls.costPrice | Cost price in the MLS. |
mls.saleCompany | Company responsible for the sale. |
mls.sourceCompany | Company that sourced the item. |
mls.lineCode | Code for the line item. |
mls.poNumber | Purchase order number. |
mls.poCreateDate | Date when the purchase order was created. |
mls.poLineID | Line ID for the purchase order. |
mls.mlsType | Type of MLS entry. |
mls.debitAccount | The account used to record debits associated with the transaction, typically for accounting purposes. |
mls.debitCompany | The company associated with the debit transaction, typically used for accounting and financial tracking. |
mls.debitControl | The type of control associated with the debit transaction, typically used for accounting purposes. |
mls.feeID | A unique identifier for the fee associated with the transaction, used for tracking and accounting purposes. |
mls.saleAccount | An account used to record the sales transactions associated with the repair order, typically for accounting and inventory management purposes. |
mls.saleControl | The type of control associated with the sale transaction, typically used for accounting purposes. |
Order Status & DMS Status Information
Status Name | Description |
---|---|
O | OPEN - The repair order is currently active and work is ongoing. |
P | PRE_INVOICED - The repair order is in the final review stage before billing. |
C | CLOSED - The repair order is completed and all services have been finalized. |
Important Note
Order status and dmsStatus can have different values over the complete lifecycle of a Service order.