API Reference

All endpoints follow the JSON:API specification. Set Content-Type: application/vnd.api+json on write requests and expect the same in responses.

Swagger UI
Authentication

All requests must include a bearer token in the Authorization header.

Header

Authorization: Bearer <your-api-key>

Example request

curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/menu_items"

Attributes

Name Type Required Description
id uuid required Reporting ID
carbon_id uuid required The id within the POS
adjustment_type adjustment_type percent flat credit_payment round_denomination required The type of the adjustment (percent, flat, credit_payment, round_denomination)
name string required The reporting display name for the adjustment
tags string[] required Categorization labels for grouping and filtering adjustments

Endpoints

GET /api/json/adjustments/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/adjustments/<id>"
GET /api/json/adjustments read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/adjustments"
POST /api/json/adjustments create

Accepted Fields

Name Type Required
carbon_id uuid required
The id within the POS
name string required
The reporting display name for the adjustment
state adjustment_state active voided required
Whether the adjustment definition is currently available for use
tags string[] required
Categorization labels for grouping and filtering adjustments
adjustment_type adjustment_type percent flat credit_payment round_denomination required
The type of the adjustment (percent, flat, credit_payment, round_denomination)
Example request 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "attributes": {
      "name": "example",
      "state": "example",
      "tags": "example",
      "adjustment_type": "example"
    },
    "type": "adjustment",
    "relationships": {
      "carbon": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "carbon"
        }
      }
    }
  }
}' \
  "https://reports.quikserve.com/api/json/adjustments"

Attributes

Name Type Required Description
id uuid required Reporting ID
carbon_id uuid required The id within the POS
identifier string required A unique code for the discount
discount_type string required The type of the discount
name string required The reporting display name for the discount
tags string[] required Categorization labels for grouping and filtering discounts

Endpoints

GET /api/json/discounts/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/discounts/<id>"
GET /api/json/discounts read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/discounts"
POST /api/json/discounts create

Accepted Fields

Name Type Required
carbon_id uuid required
The id within the POS
name string required
The reporting display name for the discount
state discount_state active inactive required
Whether the discount is currently available for use
tags string[] required
Categorization labels for grouping and filtering discounts
discount_type string required
The type of the discount
identifier string required
A unique code for the discount
Example request 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "attributes": {
      "name": "example",
      "state": "example",
      "identifier": "example",
      "tags": "example",
      "discount_type": "example"
    },
    "type": "discount",
    "relationships": {
      "carbon": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "carbon"
        }
      }
    }
  }
}' \
  "https://reports.quikserve.com/api/json/discounts"

Attributes

Name Type Required Description
id uuid required Reporting ID
carbon_id uuid required The id within the POS
first_name string required The employee's first name
last_name string optional The employee's last name
payroll_id string optional External payroll system identifier for the employee
terminated boolean required Whether the employee is no longer active at the organization
unknown boolean required Whether the employee is no longer active at the organization

Endpoints

GET /api/json/employees/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/employees/<id>"
GET /api/json/employees read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/employees"
POST /api/json/employees create

Accepted Fields

Name Type Required
carbon_id uuid required
The id within the POS
first_name string required
The employee's first name
last_name string optional
The employee's last name
payroll_id string optional
External payroll system identifier for the employee
terminated boolean required
Whether the employee is no longer active at the organization
Example request 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "attributes": {
      "terminated": true,
      "first_name": "example",
      "last_name": "example",
      "payroll_id": "example"
    },
    "type": "employee",
    "relationships": {
      "carbon": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "carbon"
        }
      }
    }
  }
}' \
  "https://reports.quikserve.com/api/json/employees"

Attributes

Name Type Required Description
id uuid required Primary key
name string required The descriptive name for the category
tag string required Items with this tag will belong to the categoery

Endpoints

GET /api/json/item_categories/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/item_categories/<id>"
GET /api/json/item_categories read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/item_categories"

Attributes

Name Type Required Description
id uuid required The reporting identifier for the location
name string required The display name or store number for the location
carbon_id string required The pos level identifier
state location_state active inactive required The active state for the location

Endpoints

GET /api/json/locations/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/locations/<id>"
GET /api/json/locations read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/locations"
PATCH /api/json/locations/:id update

Accepted Fields

Name Type Required
name string required
The display name or store number for the location
carbon_id string required
The pos level identifier
state location_state active inactive required
The active state for the location
Example request 
curl -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "attributes": {
      "name": "example",
      "state": "example",
      "carbon_id": "example"
    },
    "type": "location"
  }
}' \
  "https://reports.quikserve.com/api/json/locations/<id>"

Attributes

Name Type Required Description
id uuid required
name string required
state location_state active inactive required

Relationships

Name Type Resource Include path
market_locations has many market_location ?include=market_locations
location belongs to location ?include=market_locations.location

Endpoints

GET /api/json/markets/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/markets/<id>"
GET /api/json/markets read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/markets"
POST /api/json/markets create

Accepted Fields

Name Type Required
name string required
Example request 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "attributes": {
      "name": "example"
    },
    "type": "market"
  }
}' \
  "https://reports.quikserve.com/api/json/markets"
PATCH /api/json/markets/:id update

Accepted Fields

Name Type Required
name string required
state location_state active inactive required
Example request 
curl -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "attributes": {
      "name": "example",
      "state": "example"
    },
    "type": "market"
  }
}' \
  "https://reports.quikserve.com/api/json/markets/<id>"
DELETE /api/json/markets/:id destroy
Example request 
curl -X DELETE \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/markets/<id>"

Attributes

Name Type Required Description
id uuid required
market_id uuid required
location_id uuid required

Relationships

Name Type Resource Include path
location belongs to location ?include=location
market belongs to market ?include=market

Endpoints

GET /api/json/market-locations/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/market-locations/<id>"
GET /api/json/market-locations read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/market-locations"
POST /api/json/market-locations create

Accepted Fields

Name Type Required
market_id uuid required
location_id uuid required
Example request 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "attributes": {},
    "type": "market_location",
    "relationships": {
      "location": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "location"
        }
      },
      "market": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "market"
        }
      }
    }
  }
}' \
  "https://reports.quikserve.com/api/json/market-locations"
DELETE /api/json/market-locations/:id destroy
Example request 
curl -X DELETE \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/market-locations/<id>"

Attributes

Name Type Required Description
id uuid required Reporting ID
carbon_id uuid required The id within the POS
name string required The reporting display name for the item
plu string optional Price look-up code used to identify the item at the point of sale
tags string[] required Categorization labels for grouping and filtering menu items

Endpoints

GET /api/json/menu_items/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/menu_items/<id>"
GET /api/json/menu_items read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/menu_items"
POST /api/json/menu_items create

Accepted Fields

Name Type Required
carbon_id uuid required
The id within the POS
name string required
The reporting display name for the item
state menu_item_state active inactive resync required
The active state of the item
tags string[] required
Categorization labels for grouping and filtering menu items
plu string optional
Price look-up code used to identify the item at the point of sale
Example request 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "attributes": {
      "name": "example",
      "state": "example",
      "tags": "example",
      "plu": "example"
    },
    "type": "menu_item",
    "relationships": {
      "carbon": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "carbon"
        }
      }
    }
  }
}' \
  "https://reports.quikserve.com/api/json/menu_items"

Attributes

Name Type Required Description
id uuid required Reporting ID
carbon_id uuid required The id within the POS
payment_type payment_type credit cash gift online other required The type of payment made
state payment_state active voided optional The state of the payment
card_type string optional If the payment was credit, this value holds the card brand.
amount decimal required The payment amount
sale_business_date date optional The business day the order is associated with.
sale_id uuid required
location_id uuid required

Relationships

Name Type Resource Include path
sale belongs to sale ?include=sale
location belongs to location ?include=location

Endpoints

GET /api/json/payments/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/payments/<id>"
GET /api/json/payments read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/payments"

Attributes

Name Type Required Description
id uuid required Reporting ID
carbon_id uuid required The id within the POS
completed_at utc_datetime required The moment the order was completed
business_date date optional The business day the order is associated with.
state sale_state completed voided optional The active state of the sale
destination destination drive_thru dine_in take_out delivery curbside pickup third_party optional The destination for the sale
entry_method entry_method terminal kiosk online optional The mechanism by which the order was created
net_total decimal required The net total of the sale
tax_total decimal required The total sales tax applied
discount_total decimal required The total discount applied to the order
gc_sold_count integer required Number of gift cards sold in this sale
gc_sold_amount decimal required Total value of gift cards sold in this sale
third_party_provider string optional The service providing a third party order
delivery_provider string optional The service delivering the order
employee_id uuid optional
location_id uuid required

Relationships

Name Type Resource Include path
location belongs to location ?include=location
payments has many payment ?include=payments
employee belongs to employee ?include=employee
sale_taxes has many sale_tax ?include=sale_taxes
tax_card belongs to tax_card ?include=sale_taxes.tax_card
sale_items has many sale_item ?include=sale_items
menu_item belongs to menu_item ?include=sale_items.menu_item
parent_item belongs to sale_item ?include=sale_items.parent_item
sale_discounts has many sale_discount ?include=sale_discounts
discount belongs to discount ?include=sale_discounts.discount
sale_adjustments has many sale_adjustment ?include=sale_adjustments
adjustment belongs to adjustment ?include=sale_adjustments.adjustment

Endpoints

GET /api/json/sales/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/sales/<id>"
GET /api/json/sales read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/sales"
POST /api/json/sales create

Accepted Fields

Name Type Required
carbon_id uuid required
The id within the POS
location_id uuid required
state sale_state completed voided optional
The active state of the sale
destination destination drive_thru dine_in take_out delivery curbside pickup third_party optional
The destination for the sale
entry_method entry_method terminal kiosk online optional
The mechanism by which the order was created
completed_at utc_datetime required
The moment the order was completed
business_date date optional
The business day the order is associated with.
net_total decimal required
The net total of the sale
tax_total decimal required
The total sales tax applied
discount_total decimal required
The total discount applied to the order
gc_sold_count integer required
Number of gift cards sold in this sale
gc_sold_amount decimal required
Total value of gift cards sold in this sale
third_party_provider string optional
The service providing a third party order
delivery_provider string optional
The service delivering the order

Arguments

Name Type Required
carbon_employee_id uuid optional
Example request 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "attributes": {
      "state": "example",
      "destination": "example",
      "completed_at": "example",
      "business_date": "example",
      "entry_method": "example",
      "net_total": "0.00",
      "tax_total": "0.00",
      "discount_total": "0.00",
      "gc_sold_count": 0,
      "gc_sold_amount": "0.00",
      "third_party_provider": "example",
      "delivery_provider": "example"
    },
    "type": "sale",
    "relationships": {
      "carbon": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "carbon"
        }
      },
      "location": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "location"
        }
      }
    }
  }
}' \
  "https://reports.quikserve.com/api/json/sales"

Attributes

Name Type Required Description
id uuid required Reporting ID
carbon_adjustment_id uuid required The POS adjustment definition id
state adjustment_state active voided optional The state of the applied adjustment
amount decimal required The signed minor-unit amount of the applied adjustment (can be negative for round_denomination)
sale_completed_at utc_datetime optional When the parent sale was completed, denormalized to avoid joins in time-range queries
sale_business_date date optional The business day the order is associated with.
sale_id uuid required
adjustment_id uuid required

Relationships

Name Type Resource Include path
adjustment belongs to adjustment ?include=adjustment
sale belongs to sale ?include=sale

Endpoints

GET /api/json/sale_adjustments/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/sale_adjustments/<id>"
GET /api/json/sale_adjustments read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/sale_adjustments"

Attributes

Name Type Required Description
id uuid required Reporting ID
state sale_item_state active deleted voided required Whether this line item is active or was deleted from the order
carbon_id uuid required The id within the POS
sale_amount decimal required The sale amount for the item
quantity integer optional The number of the items sold on the order
tax_amount decimal required The tax resulting from the item
discount_amount decimal required The discount amount applied to the item
modifier string optional The ingredient modifier (extra, light, etc)
variation string optional The variation of the item (size, color, etc)
sale_completed_at utc_datetime optional When the parent sale was completed, denormalized to avoid joins in time-range queries
sale_business_date date optional The business day the order is associated with.
parent_item_id uuid optional
sale_id uuid required
menu_item_id uuid required
location_id uuid required

Relationships

Name Type Resource Include path
location belongs to location ?include=location
sale belongs to sale ?include=sale
menu_item belongs to menu_item ?include=menu_item
sub_items has many sale_item ?include=sub_items
parent_item belongs to sale_item ?include=parent_item

Endpoints

GET /api/json/sales_item/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/sales_item/<id>"
GET /api/json/sales_item read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/sales_item"

Attributes

Name Type Required Description
id uuid required Reporting ID
amount decimal required The amount of tax applied
carbon_tax_card_id uuid required The POS tax_card id
sale_business_date date optional The business day the order is associated with.
tax_card_id uuid required
sale_id uuid required

Relationships

Name Type Resource Include path
tax_card belongs to tax_card ?include=tax_card
sale belongs to sale ?include=sale

Endpoints

GET /api/json/sale_tax_cards/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/sale_tax_cards/<id>"
GET /api/json/sale_tax_cards read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/sale_tax_cards"

Attributes

Name Type Required Description
id uuid required Reporting ID
name string required The descriptive name for the tax card
carbon_id uuid required The id within the POS

Relationships

Name Type Resource Include path
sale_taxes has many sale_tax ?include=sale_taxes

Endpoints

GET /api/json/tax_cards/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/tax_cards/<id>"
GET /api/json/tax_cards read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/tax_cards"

Attributes

Name Type Required Description
id uuid required Reporting ID
carbon_id uuid required The id within the POS
clocked_in_at utc_datetime required UTC timestamp of when the employee clocked in
clocked_out_at utc_datetime optional UTC timestamp of when the employee clocked out; nil for open punches
pay_rate decimal required Hourly pay rate in dollars applicable to this punch
business_date date optional The business day the order is associated with.
location_id uuid required
employee_id uuid required

Relationships

Name Type Resource Include path
location belongs to location ?include=location
employee belongs to employee ?include=employee
breaks has many time_punch_break ?include=breaks

Endpoints

GET /api/json/time_punches/:id read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/time_punches/<id>"
GET /api/json/time_punches read
Example request 
curl \
  -H "Authorization: Bearer <your-api-key>" \
  "https://reports.quikserve.com/api/json/time_punches"
POST /api/json/time_punches create

Accepted Fields

Name Type Required
clocked_in_at utc_datetime required
UTC timestamp of when the employee clocked in
clocked_out_at utc_datetime optional
UTC timestamp of when the employee clocked out; nil for open punches
pay_rate decimal required
Hourly pay rate in dollars applicable to this punch
carbon_id uuid required
The id within the POS
business_date date optional
The business day the order is associated with.

Arguments

Name Type Required
carbon_employee_id uuid required
carbon_location_id string required
breaks map[] optional
Example request 
curl -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "attributes": {
      "clocked_in_at": "example",
      "clocked_out_at": "example",
      "pay_rate": "0.00",
      "business_date": "example"
    },
    "type": "time_punch",
    "relationships": {
      "carbon": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "carbon"
        }
      }
    }
  }
}' \
  "https://reports.quikserve.com/api/json/time_punches"