B2B

B2BB2XB2B CORE COMMERCEB2X CORE COMMERCE

Query and manage Business Units, Associates, Quotes, and Order approvals with the Core Subgraph.

Queries

Query Business Units

QUERYbusinessUnits
Returns the Business Units that the current Associate belongs to, directly or through inheritance. Returns up to 100 Business Units. To walk the hierarchy, use parentUnit and childUnits.

Requires a signed-in Customer.

Output:BusinessUnit
Request Example:graphql
query GetBusinessUnits {
  businessUnits { id key name unitType }
}
Response Example:json
{
  "data": {
    "businessUnits": [
      {
        "id": "AQQAAaWkpaRVVUVUpVRVVVVUVVQAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "key": "acme-group",
        "name": "Acme Group",
        "unitType": "COMPANY"
      },
      {
        "id": "AQQAAVVUVVRVVUVUpVRVVVVUVVQAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "key": "acme-uk",
        "name": "Acme UK Ltd",
        "unitType": "DIVISION"
      }
    ]
  }
}

Get Business Unit by key

QUERYbusinessUnit
Returns a Business Unit by its key. Returns null if the current Associate can't view it.

Requires a signed-in Customer.

Arguments
key​
String​

Key of the Business Unit. If omitted, returns the active Business Unit of the session.

Output:BusinessUnit
Request Example:graphql
query GetBusinessUnit {
  businessUnit(key: "acme-uk") {
    id
    key
    name
    unitType
    parentUnit { key name }
    stores { key name }
    associates { fullName email }
  }
}
Response Example:json
{
  "data": {
    "businessUnit": {
      "id": "AQQAAVVUVVRVVUVUpVRVVVVUVVQAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "key": "acme-uk",
      "name": "Acme UK Ltd",
      "unitType": "DIVISION",
      "parentUnit": { "key": "acme-group", "name": "Acme Group" },
      "stores": [{ "key": "uk-store", "name": "UK Store" }],
      "associates": [
        { "fullName": "Sam Taylor", "email": "sam.taylor@example.com" },
        { "fullName": "John Smith", "email": "john.smith@example.com" }
      ]
    }
  }
}

Get active Business Unit

QUERYactiveBusinessUnit
Returns the active Business Unit of the session. Returns null if the shopper isn't signed in or hasn't selected a Business Unit. To select one, call PUT /{project}/main/session/business-unit on the identity host.
Output:BusinessUnit
Request Example:graphql
query GetActiveBusinessUnit {
  activeBusinessUnit {
    id
    key
    name
    status
    currencies
    assignableRoles { key name }
  }
}
Response Example:json
{
  "data": {
    "activeBusinessUnit": {
      "id": "AQQAAVVUVVRVVUVUpVRVVVVUVVQAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "key": "acme-uk",
      "name": "Acme UK Ltd",
      "status": "ACTIVE",
      "currencies": ["GBP"],
      "assignableRoles": [
        { "key": "approver", "name": "Approver" },
        { "key": "buyer", "name": "Buyer" }
      ]
    }
  }
}

Query Quote Requests

QUERYquoteRequests

Returns the Quote Requests of the active Business Unit that the current Associate can view, newest first.

Requires an active Business Unit. Without one, the query fails with a BUSINESS_UNIT_REQUIRED error.
Arguments
filter​
QuoteRequestFilter​

Filters the Quote Requests.

first​
Int​
Maximum number of results to return, from 0 to 500. Default: 20.
Default: 20​
after​
String​
Cursor of the item after which the page starts. Take it from edges.cursor or pageInfo.endCursor. A cursor that this API didn't issue fails the query.
Output:QuoteRequestConnection
Request Example:graphql
query GetQuoteRequests {
  quoteRequests(filter: {quoteRequestState: [SUBMITTED, ACCEPTED]}, first: 10) {
    pageInfo { hasNextPage endCursor }
    nodes {
      id
      quoteRequestState
      itemCount
      total { formatted }
    }
  }
}
Response Example:json
{
  "data": {
    "quoteRequests": {
      "pageInfo": { "hasNextPage": false, "endCursor": "AW9nZ3NkdDsw" },
      "nodes": [
        {
          "id": "AQcAAYiJiImIiEiJqImIiIiJiIkAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
          "quoteRequestState": "SUBMITTED",
          "itemCount": 20,
          "total": { "formatted": "£1,134.95" }
        }
      ]
    }
  }
}

Get Quote Request by ID

QUERYquoteRequest
Returns a Quote Request of the active Business Unit. Returns null if it doesn't exist or the current Associate can't view it.
Requires an active Business Unit. Without one, the query fails with a BUSINESS_UNIT_REQUIRED error.
Arguments
id​
ID​

ID of the Quote Request.

Output:QuoteRequest
Request Example:graphql
query GetQuoteRequest {
  quoteRequest(
    id: "AQcAAYiJiImIiEiJqImIiIiJiIkAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA"
  ) {
    id
    quoteRequestState
    comment
    lines { productName quantity }
    total { formatted }
  }
}
Response Example:json
{
  "data": {
    "quoteRequest": {
      "id": "AQcAAYiJiImIiEiJqImIiIiJiIkAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "quoteRequestState": "SUBMITTED",
      "comment": "Can you offer a better price for 10 chairs?",
      "lines": [
        { "productName": "Oak Dining Chair", "quantity": 10 },
        { "productName": "Linen Cushion", "quantity": 10 }
      ],
      "total": { "formatted": "£1,134.95" }
    }
  }
}

Query Quotes

QUERYquotes

Returns the Quotes of the active Business Unit that the current Associate can view, newest first.

Requires an active Business Unit. Without one, the query fails with a BUSINESS_UNIT_REQUIRED error.
Arguments
filter​
QuoteFilter​

Filters the Quotes.

first​
Int​
Maximum number of results to return, from 0 to 500. Default: 20.
Default: 20​
after​
String​
Cursor of the item after which the page starts. Take it from edges.cursor or pageInfo.endCursor. A cursor that this API didn't issue fails the query.
Output:QuoteConnection
Request Example:graphql
query GetQuotes {
  quotes(filter: {quoteState: [PENDING]}, first: 10) {
    pageInfo { hasNextPage endCursor }
    edges {
      cursor
      node { id quoteState expiresAt }
    }
  }
}
Response Example:json
{
  "data": {
    "quotes": {
      "pageInfo": { "hasNextPage": false, "endCursor": "AW9nZ3NkdDsw" },
      "edges": [
        {
          "cursor": "AW9nZ3NkdDsw",
          "node": {
            "id": "AQYAAXd2d3Z3d0d2p3Z3d3d2d3YAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
            "quoteState": "PENDING",
            "expiresAt": "2026-10-31T23:59:59.000Z"
          }
        }
      ]
    }
  }
}

Get Quote by ID

QUERYquote
Returns a Quote of the active Business Unit. Returns null if it doesn't exist or the current Associate can't view it.
Requires an active Business Unit. Without one, the query fails with a BUSINESS_UNIT_REQUIRED error.
Arguments
id​
ID​

ID of the Quote.

Output:Quote
Request Example:graphql
query GetQuote {
  quote(id: "AQYAAXd2d3Z3d0d2p3Z3d3d2d3YAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA") {
    id
    quoteState
    expiresAt
    lines { productName quantity }
    total { formatted }
    availableActions
  }
}
Response Example:json
{
  "data": {
    "quote": {
      "id": "AQYAAXd2d3Z3d0d2p3Z3d3d2d3YAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "quoteState": "PENDING",
      "expiresAt": "2026-10-31T23:59:59.000Z",
      "lines": [
        { "productName": "Oak Dining Chair", "quantity": 10 },
        { "productName": "Linen Cushion", "quantity": 10 }
      ],
      "total": { "formatted": "£1,134.95" },
      "availableActions": ["ACCEPT", "RENEGOTIATE", "DECLINE"]
    }
  }
}

Query Approval Flows

QUERYapprovals

Returns the Approval Flows of the active Business Unit that the current Associate can view.

Requires an active Business Unit. Without one, the query fails with a BUSINESS_UNIT_REQUIRED error.
Arguments
filter​
ApprovalFlowFilter​

Filters the Approval Flows.

first​
Int​
Maximum number of results to return, from 0 to 500. Default: 20.
Default: 20​
after​
String​
Cursor of the item after which the page starts. Take it from edges.cursor or pageInfo.endCursor. A cursor that this API didn't issue fails the query.
Output:ApprovalFlowConnection
Request Example:graphql
query GetApprovals {
  approvals(filter: {approvalState: [PENDING]}, first: 20) {
    pageInfo { hasNextPage endCursor }
    nodes {
      id
      approvalState
      total { formatted }
      requestedBy { fullName }
    }
  }
}
Response Example:json
{
  "data": {
    "approvals": {
      "pageInfo": { "hasNextPage": false, "endCursor": "AW9nZ3NkdDsw" },
      "nodes": [
        {
          "id": "AQkAAbGzs7XBwk0cjh_x8vP19fcAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
          "approvalState": "PENDING",
          "total": { "formatted": "£5,340.00" },
          "requestedBy": { "fullName": "John Smith" }
        }
      ]
    }
  }
}

Get Approval Flow by ID

QUERYapproval
Returns an Approval Flow of the active Business Unit. Returns null if it doesn't exist or the current Associate can't view it.
Requires an active Business Unit. Without one, the query fails with a BUSINESS_UNIT_REQUIRED error.
Arguments
id​
ID​

ID of the Approval Flow.

Output:ApprovalFlow
Request Example:graphql
query GetApproval {
  approval(id: "AQkAAbGzs7XBwk0cjh_x8vP19fcAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA") {
    id
    approvalState
    orderReference
    requestedBy { fullName }
    matchedRules { name }
    currentTierPendingApproverRoles { key name }
    availableActions
  }
}
Response Example:json
{
  "data": {
    "approval": {
      "id": "AQkAAbGzs7XBwk0cjh_x8vP19fcAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "approvalState": "PENDING",
      "orderReference": "33333333-3333-4333-a333-333333333333",
      "requestedBy": { "fullName": "John Smith" },
      "matchedRules": [{ "name": "Orders over £5,000" }],
      "currentTierPendingApproverRoles": [
        { "key": "approver", "name": "Approver" }
      ],
      "availableActions": ["APPROVE", "REJECT"]
    }
  }
}

Query Approval Rules

QUERYapprovalRules

Returns the Approval Rules of the active Business Unit.

Requires an active Business Unit. Without one, the query fails with a BUSINESS_UNIT_REQUIRED error.
Arguments
filter​
ApprovalRuleFilter​

Filters the Approval Rules.

first​
Int​
Maximum number of results to return, from 0 to 500. Default: 20.
Default: 20​
after​
String​
Cursor of the item after which the page starts. Take it from edges.cursor or pageInfo.endCursor. A cursor that this API didn't issue fails the query.
Output:ApprovalRuleConnection
Request Example:graphql
query GetApprovalRules {
  approvalRules(filter: {approvalRuleState: [ACTIVE]}, first: 20) {
    totalCount
    nodes { id key name approvalRuleState }
  }
}
Response Example:json
{
  "data": {
    "approvalRules": {
      "totalCount": 1,
      "nodes": [
        {
          "id": "AQoAAcHDw8XR0k4fnx6hoqOlpacAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
          "key": "orders-over-5000",
          "name": "Orders over £5,000",
          "approvalRuleState": "ACTIVE"
        }
      ]
    }
  }
}

Get Approval Rule by ID

QUERYapprovalRule
Returns an Approval Rule of the active Business Unit. Returns null if it doesn't exist or the current Associate can't view it.
Requires an active Business Unit. Without one, the query fails with a BUSINESS_UNIT_REQUIRED error.
Arguments
id​
ID​

ID of the Approval Rule.

Output:ApprovalRule
Request Example:graphql
query GetApprovalRule {
  approvalRule(
    id: "AQoAAcHDw8XR0k4fnx6hoqOlpacAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA"
  ) {
    id
    name
    approvalRuleState
    conditions { field operator }
    requesterRoles { key }
  }
}
Response Example:json
{
  "data": {
    "approvalRule": {
      "id": "AQoAAcHDw8XR0k4fnx6hoqOlpacAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "name": "Orders over £5,000",
      "approvalRuleState": "ACTIVE",
      "conditions": [{ "field": "ORDER_TOTAL", "operator": "GT" }],
      "requesterRoles": [{ "key": "buyer" }]
    }
  }
}

Mutations

Create Business Unit

MUTATIONcreateBusinessUnit
Creates a Division under an existing Business Unit. Companies can't be created with this API. For how the Division is set up, see CreateBusinessUnitInput.
Arguments
input​
CreateBusinessUnitInput​

The Division to create.

Output:BusinessUnitResult
Request Example:graphql
mutation CreateBusinessUnit {
  createBusinessUnit(
    input: {key: "acme-uk-north", name: "Acme UK North", parentUnitKey: "acme-uk", contactEmail: "north@example.com"}
  ) {
    businessUnit { id key name unitType }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "createBusinessUnit": {
      "businessUnit": {
        "id": "AQQAAbW0tbRVVUVUpVRVVVVUVVQAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "key": "acme-uk-north",
        "name": "Acme UK North",
        "unitType": "DIVISION"
      },
      "userErrors": []
    }
  }
}

Change Business Unit name

MUTATIONchangeBusinessUnitName
Changes the name of the active Business Unit. Requires the UPDATE_BUSINESS_UNIT_DETAILS permission. Without it, the mutation is refused with FORBIDDEN_ACTION.
Arguments
name​
String​

New name of the Business Unit.

Output:BusinessUnitResult
Request Example:graphql
mutation ChangeBusinessUnitName {
  changeBusinessUnitName(name: "Acme UK Limited") {
    businessUnit { id name }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "changeBusinessUnitName": {
      "businessUnit": {
        "id": "AQQAAVVUVVRVVUVUpVRVVVVUVVQAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "name": "Acme UK Limited"
      },
      "userErrors": []
    }
  }
}

Set Business Unit contact email

MUTATIONsetBusinessUnitContactEmail
Sets or removes the contact email address of the active Business Unit. Requires the UPDATE_BUSINESS_UNIT_DETAILS permission. Without it, the mutation is refused with FORBIDDEN_ACTION.
Arguments
contactEmail​
String​
Email address to set. If omitted or null, the current contact email address is removed.
Output:BusinessUnitResult
Request Example:graphql
mutation SetBusinessUnitContactEmail {
  setBusinessUnitContactEmail(contactEmail: "orders@example.com") {
    businessUnit { id contactEmail }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setBusinessUnitContactEmail": {
      "businessUnit": {
        "id": "AQQAAVVUVVRVVUVUpVRVVVVUVVQAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "contactEmail": "orders@example.com"
      },
      "userErrors": []
    }
  }
}

Add Business Unit address

MUTATIONaddBusinessUnitAddress
Adds an address to the active Business Unit and returns it. Requires the UPDATE_BUSINESS_UNIT_DETAILS permission. Without it, the mutation is refused with FORBIDDEN_ACTION.
Arguments
input​
AddressBookInput​

The address to add.

Output:SavedAddressResult
Request Example:graphql
mutation AddBusinessUnitAddress {
  addBusinessUnitAddress(
    input: {name: "Jane Doe", line1: "1 Example Street", city: "London", postalCode: "SW1A 1AA", country: "GB"}
  ) {
    address { id name line1 city postalCode country }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "addBusinessUnitAddress": {
      "address": {
        "id": "ARMDAVVUVVRVVUVUpVRVVVVUVVQBCGhLN2tMOW1PAAEAAAAAAAEAAAABAAEAAA",
        "name": "Jane Doe",
        "line1": "1 Example Street",
        "city": "London",
        "postalCode": "SW1A 1AA",
        "country": "GB"
      },
      "userErrors": []
    }
  }
}

Update Business Unit address

MUTATIONupdateBusinessUnitAddress
Updates an address of the active Business Unit. Stored address fields that the input doesn't cover, such as phone numbers, keep their values. An unknown address is refused with ADDRESS_NOT_FOUND.
Arguments
input​
UpdateAddressInput​

The address to update and its new values.

Output:SavedAddressResult
Request Example:graphql
mutation UpdateBusinessUnitAddress {
  updateBusinessUnitAddress(
    input: {addressId: "ARMDAVVUVVRVVUVUpVRVVVVUVVQBCGhLN2tMOW1PAAEAAAAAAAEAAAABAAEAAA", address: {name: "Jane Doe", line1: "1 Example Street", line2: "Floor 3", city: "London", postalCode: "SW1A 1AA", country: "GB"}}
  ) {
    address { id name line1 line2 city }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "updateBusinessUnitAddress": {
      "address": {
        "id": "ARMDAVVUVVRVVUVUpVRVVVVUVVQBCGhLN2tMOW1PAAEAAAAAAAEAAAABAAEAAA",
        "name": "Jane Doe",
        "line1": "1 Example Street",
        "line2": "Floor 3",
        "city": "London"
      },
      "userErrors": []
    }
  }
}

Remove Business Unit address

MUTATIONremoveBusinessUnitAddress
Removes an address from the active Business Unit. On success, address is null. An unknown address is refused with ADDRESS_NOT_FOUND.
Arguments
id​
ID​

ID of the address to remove.

Output:SavedAddressResult
Request Example:graphql
mutation RemoveBusinessUnitAddress {
  removeBusinessUnitAddress(
    id: "ARMDAVVUVVRVVUVUpVRVVVVUVVQBCGhLN2tMOW1PAAEAAAAAAAEAAAABAAEAAA"
  ) {
    address { id }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "removeBusinessUnitAddress": { "address": null, "userErrors": [] }
  }
}

Add Associate

MUTATIONaddAssociate

Adds an existing Customer as an Associate of the active Business Unit, with the given Associate Roles.

Requires the UPDATE_ASSOCIATES permission, held directly or inherited. Without it, the mutation is refused with FORBIDDEN_ACTION, whether or not the email address exists. An email address without a Customer account is refused with CUSTOMER_NOT_FOUND.
Arguments
input​
AddAssociateInput​

The Customer to add and the roles to assign.

Output:AssociateResult
Request Example:graphql
mutation AddAssociate {
  addAssociate(
    input: {email: "john.smith@example.com", roleKeys: ["buyer"], inheritance: ENABLED}
  ) {
    associate {
      id
      email
      roles { key name }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "addAssociate": {
      "associate": {
        "id": "AREDAVVUVVRVVUVUpVRVVVVUVVQAxMTFxERERESlREVERERERAEAAAABAAEAAA",
        "email": "john.smith@example.com",
        "roles": [{ "key": "buyer", "name": "Buyer" }]
      },
      "userErrors": []
    }
  }
}

Update Associate Roles

MUTATIONupdateAssociateRoles
Replaces the Associate Roles that an Associate holds in the Business Unit identified by associateId. Requires the UPDATE_ASSOCIATES permission in that Business Unit.
This mutation can remove UPDATE_ASSOCIATES from the last Associate who holds it, including the current Associate. The Business Unit is then left in the same state that removeAssociate describes: nobody can manage its Associates through this API.
Arguments
input​
UpdateAssociateRolesInput​

The Associate to update and their new roles.

Output:AssociateResult
Request Example:graphql
mutation UpdateAssociateRoles {
  updateAssociateRoles(
    input: {associateId: "AREDAVVUVVRVVUVUpVRVVVVUVVQAxMTFxERERESlREVERERERAEAAAABAAEAAA", roleKeys: ["buyer", "approver"]}
  ) {
    associate {
      id
      roles { key name }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "updateAssociateRoles": {
      "associate": {
        "id": "AREDAVVUVVRVVUVUpVRVVVVUVVQAxMTFxERERESlREVERERERAEAAAABAAEAAA",
        "roles": [
          { "key": "buyer", "name": "Buyer" },
          { "key": "approver", "name": "Approver" }
        ]
      },
      "userErrors": []
    }
  }
}

Remove Associate

MUTATIONremoveAssociate
Removes an Associate, with all their roles, from the Business Unit identified by id. Requires the UPDATE_ASSOCIATES permission in that Business Unit. Without it, the mutation is refused with FORBIDDEN_ACTION. On success, associate is null.
A Business Unit can end up with no associates at all, because no check ensures that anybody remains. If no Associate with UPDATE_ASSOCIATES remains, directly or inherited, no mutation in this API can add one back. Child units that inherit Associates from this Business Unit lose the removed Associate too. Before you remove the last administrator, read BusinessUnit.associates and assign the roles to their replacement.
Arguments
id​
ID​

ID of the Associate to remove.

Output:AssociateResult
Request Example:graphql
mutation RemoveAssociate {
  removeAssociate(
    id: "AREDAVVUVVRVVUVUpVRVVVVUVVQAxMTFxERERESlREVERERERAEAAAABAAEAAA"
  ) {
    associate { id }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": { "removeAssociate": { "associate": null, "userErrors": [] } }
}

Request Quote

MUTATIONrequestQuote

Requests a Quote for the Cart of the current session as it is, with its lines, addresses, Shipping Method, and prices. To quote something else, change the Cart and request again.

The Cart stays active and unchanged. The Quote Request keeps its own copy of the lines and totals, so later Cart changes don't affect it.

An empty Cart is refused with EMPTY_CART. A Cart without a shipping address is refused with SHIPPING_ADDRESS_REQUIRED. A Cart with a Discount Code is refused with QUOTE_CART_HAS_DISCOUNT_CODES.
Arguments
input​
RequestQuoteInput​

Message and purchase order number for the Quote Request.

Output:QuoteRequestResult
Request Example:graphql
mutation RequestQuote {
  requestQuote(
    input: {message: "Can you offer a better price for 10 chairs?", purchaseOrderNumber: "PO-2026-0917"}
  ) {
    quoteRequest { id quoteRequestState itemCount purchaseOrderNumber }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "requestQuote": {
      "quoteRequest": {
        "id": "AQcAAYiJiImIiEiJqImIiIiJiIkAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "quoteRequestState": "SUBMITTED",
        "itemCount": 20,
        "purchaseOrderNumber": "PO-2026-0917"
      },
      "userErrors": []
    }
  }
}

Cancel Quote Request

MUTATIONcancelQuoteRequest
Cancels a Quote Request that the Buyer no longer wants answered, and sets its state to CANCELLED.
Only a SUBMITTED Quote Request can be cancelled. Other states are refused with QUOTE_REQUEST_NOT_ACTIONABLE. An unknown ID is refused with QUOTE_REQUEST_NOT_FOUND.
Arguments
quoteRequestId​
ID​

ID of the Quote Request to cancel.

Output:QuoteRequestResult
Request Example:graphql
mutation CancelQuoteRequest {
  cancelQuoteRequest(
    quoteRequestId: "AQcAAYiJiImIiEiJqImIiIiJiIkAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA"
  ) {
    quoteRequest { id quoteRequestState }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "cancelQuoteRequest": {
      "quoteRequest": {
        "id": "AQcAAYiJiImIiEiJqImIiIiJiIkAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "quoteRequestState": "CANCELLED"
      },
      "userErrors": []
    }
  }
}

Accept Quote

MUTATIONacceptQuote
Accepts a Quote and creates an Order from it in the same step. The result returns the Order in order.
A Quote that isn't PENDING is refused with QUOTE_NOT_ACTIONABLE, and an expired Quote with QUOTE_EXPIRED. If the current Associate lacks permission, the mutation is refused with FORBIDDEN_ACTION. An unknown ID is refused with QUOTE_NOT_FOUND.
Arguments
quoteId​
ID​

ID of the Quote to accept.

Output:QuoteResult
Request Example:graphql
mutation AcceptQuote {
  acceptQuote(
    quoteId: "AQYAAXd2d3Z3d0d2p3Z3d3d2d3YAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA"
  ) {
    quote { id quoteState }
    order { id fromQuote orderState }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "acceptQuote": {
      "quote": {
        "id": "AQYAAXd2d3Z3d0d2p3Z3d3d2d3YAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "quoteState": "ACCEPTED"
      },
      "order": {
        "id": "AQIAAdPS09IzM0MyozIzMzMyMzIAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "fromQuote": true,
        "orderState": "OPEN"
      },
      "userErrors": []
    }
  }
}

Decline Quote

MUTATIONdeclineQuote
Declines a Quote and sets its state to DECLINED.
Refused on the same terms as acceptQuote.
Arguments
quoteId​
ID​

ID of the Quote to decline.

reason​
String​
Reason for declining. Stored as the buyerComment of the Quote. A blank value is ignored. Passing a reason also requires permission to renegotiate the Quote. Without it, the mutation is refused with FORBIDDEN_ACTION.
Output:QuoteResult
Request Example:graphql
mutation DeclineQuote {
  declineQuote(
    quoteId: "AQYAAXd2d3Z3d0d2p3Z3d3d2d3YAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA"
    reason: "We found a better offer."
  ) {
    quote { id quoteState buyerComment availableActions }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "declineQuote": {
      "quote": {
        "id": "AQYAAXd2d3Z3d0d2p3Z3d3d2d3YAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "quoteState": "DECLINED",
        "buyerComment": "We found a better offer.",
        "availableActions": []
      },
      "userErrors": []
    }
  }
}

Renegotiate Quote

MUTATIONrenegotiateQuote
Asks the Seller to renegotiate a Quote. The Quote state changes to DECLINED_FOR_RENEGOTIATION, and message is stored as its buyerComment.
Refused on the same terms as acceptQuote.
Arguments
input​
RenegotiateQuoteInput​

The Quote to renegotiate and the message to the Seller.

Output:QuoteResult
Request Example:graphql
mutation RenegotiateQuote {
  renegotiateQuote(
    input: {quoteId: "AQYAAXd2d3Z3d0d2p3Z3d3d2d3YAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA", message: "Can you include free delivery?"}
  ) {
    quote { id quoteState buyerComment availableActions }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "renegotiateQuote": {
      "quote": {
        "id": "AQYAAXd2d3Z3d0d2p3Z3d3d2d3YAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "quoteState": "DECLINED_FOR_RENEGOTIATION",
        "buyerComment": "Can you include free delivery?",
        "availableActions": []
      },
      "userErrors": []
    }
  }
}

Approve Order

MUTATIONapproveOrder

Records the approval of the current Associate on the Approval Flow of an Order. The Order itself doesn't change.

An Order without an Approval Flow in the active Business Unit is refused with ORDER_NOT_FOUND. If the flow can't be approved, the mutation is refused with APPROVAL_NOT_PENDING, or with FORBIDDEN_ACTION if the Associate lacks permission.
Arguments
orderId​
ID​

ID of the Order to approve.

Output:ApprovalFlowResult
Request Example:graphql
mutation ApproveOrder {
  approveOrder(
    orderId: "AQIAATMyMzIzM0MyozIzMzMyMzIAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA"
  ) {
    approvalFlow { id approvalState availableActions }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "approveOrder": {
      "approvalFlow": {
        "id": "AQkAAbGzs7XBwk0cjh_x8vP19fcAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "approvalState": "APPROVED",
        "availableActions": []
      },
      "userErrors": []
    }
  }
}

Reject Order

MUTATIONrejectOrder
Rejects the Approval Flow of an Order, which ends the flow. The Order is then cancelled if its state is OPEN or CONFIRMED.
Otherwise refused on the same terms as approveOrder.
Arguments
orderId​
ID​

ID of the Order to reject.

reason​
String​
Reason for the rejection. Returned in rejection.reason of the Approval Flow. A blank value is refused with APPROVAL_REASON_REQUIRED.
Output:ApprovalFlowResult
Request Example:graphql
mutation RejectOrder {
  rejectOrder(
    orderId: "AQIAATMyMzIzM0MyozIzMzMyMzIAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA"
    reason: "Over the monthly budget."
  ) {
    approvalFlow { id approvalState availableActions }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "rejectOrder": {
      "approvalFlow": {
        "id": "AQkAAbGzs7XBwk0cjh_x8vP19fcAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "approvalState": "REJECTED",
        "availableActions": []
      },
      "userErrors": []
    }
  }
}

Create Approval Rule

MUTATIONcreateApprovalRule

Creates an Approval Rule in the active Business Unit.

The input is checked before the Approval Rule is stored. Invalid conditions are refused with CONDITION_NOT_SUPPORTED, missing approvers with APPROVER_TIERS_REQUIRED, and unknown role keys with ASSOCIATE_ROLE_NOT_FOUND.
Arguments
input​
CreateApprovalRuleInput​

The Approval Rule to create.

Output:ApprovalRuleResult
Request Example:graphql
mutation CreateApprovalRule {
  createApprovalRule(
    input: {key: "orders-over-5000", name: "Orders over £5,000", description: "Orders above £5,000 need approval from an approver.", conditions: [{field: ORDER_TOTAL, operator: GT, amountInMinorUnits: 500000, currency: "GBP"}], approverTiers: [{groups: [{roleKeys: ["approver"]}]}], requesterRoleKeys: ["buyer"]}
  ) {
    approvalRule { id key name approvalRuleState }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "createApprovalRule": {
      "approvalRule": {
        "id": "AQoAAcHDw8XR0k4fnx6hoqOlpacAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "key": "orders-over-5000",
        "name": "Orders over £5,000",
        "approvalRuleState": "ACTIVE"
      },
      "userErrors": []
    }
  }
}

Update Approval Rule

MUTATIONupdateApprovalRule
Updates an Approval Rule of the active Business Unit. The input is checked the same way as for createApprovalRule. An unknown ID is refused with APPROVAL_RULE_NOT_FOUND.
Arguments
input​
UpdateApprovalRuleInput​

The Approval Rule to update and the fields to change.

Output:ApprovalRuleResult
Request Example:graphql
mutation UpdateApprovalRule {
  updateApprovalRule(
    input: {id: "AQoAAcHDw8XR0k4fnx6hoqOlpacAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA", name: "Orders over £2,500", conditions: [{field: ORDER_TOTAL, operator: GT, amountInMinorUnits: 250000, currency: "GBP"}]}
  ) {
    approvalRule { id name approvalRuleState }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "updateApprovalRule": {
      "approvalRule": {
        "id": "AQoAAcHDw8XR0k4fnx6hoqOlpacAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "name": "Orders over £2,500",
        "approvalRuleState": "ACTIVE"
      },
      "userErrors": []
    }
  }
}

Set Approval Rule active

MUTATIONsetApprovalRuleActive
Sets the state of an Approval Rule of the active Business Unit to ACTIVE or INACTIVE. An unknown ID is refused with APPROVAL_RULE_NOT_FOUND.
Arguments
id​
ID​

ID of the Approval Rule.

active​
Boolean​
true for ACTIVE, false for INACTIVE.
Output:ApprovalRuleResult
Request Example:graphql
mutation SetApprovalRuleActive {
  setApprovalRuleActive(
    id: "AQoAAcHDw8XR0k4fnx6hoqOlpacAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA"
    active: false
  ) {
    approvalRule { id approvalRuleState }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setApprovalRuleActive": {
      "approvalRule": {
        "id": "AQoAAcHDw8XR0k4fnx6hoqOlpacAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "approvalRuleState": "INACTIVE"
      },
      "userErrors": []
    }
  }
}

Output types

Business Unit

A Company or a Division that Associates buy for. For more information, see Business Units.
id​
ID​

Unique identifier of the Business Unit.

key​
String​

User-defined unique and immutable identifier of the Business Unit.

name​
String​

Name of the Business Unit.

unitType​
BusinessUnitType​

Type of the Business Unit.

Can be COMPANY, or DIVISION​
status​
BusinessUnitStatus​

Status of the Business Unit.

Can be ACTIVE, or INACTIVE​
contactEmail​
String​
Email address of the Business Unit, separate from the email addresses of its Associates. null if none is set.
parentUnit​
BusinessUnit​
Parent unit of the Business Unit. null for a Company, or if the current Associate can't view the parent unit.
childUnits​
Array of BusinessUnit​

Direct child units of the Business Unit. Returns up to 100 Business Units.

currencies​
Array of String​
Currency codes (ISO 4217) that the Business Unit can transact in. This is the list of currencies configured for the Project, the same list as Viewer.presentmentOptions.currencies. A Store of the Business Unit might have no prices in some of these currencies.
stores​
Array of Store​

Stores the Business Unit is associated with, including Stores inherited from its parent unit.

addresses​
Array of SavedAddress​

Addresses of the Business Unit.

associates​
Array of Associate​

Associates of the Business Unit, including Associates inherited from its parent unit.

assignableRoles​
Array of AssociateRole​
Associate Roles that can be assigned to Associates of this Business Unit: the roles the merchant marks as assignable by a Buyer. addAssociate and updateAssociateRoles accept these keys.
_ctId​
ID​
Platform identifier (UUID) of the Business Unit, for extensions that key an external system such as an ERP account by it. The public id is an opaque global identifier, so don't parse it.
Not part of the public API: an extension can read it with @requires, and it is removed from the composed API schema.

Associate

A Customer who acts within a Business Unit. The current Associate comes from the session.

id​
ID​

Unique identifier of the Associate within a specific Business Unit.

firstName​
String​
First name of the Associate. Empty if no name is recorded. This field never contains the email address, so use email if you want to show that instead.
middleName​
String​

Middle name of the Associate. Empty if they have none, or if no name is recorded.

lastName​
String​

Last name of the Associate. Empty if no name is recorded.

fullName​
String​
firstName, middleName, and lastName in that order, joined by single spaces, without the empty parts. For example, Jane Doe for a person without a middle name. Empty if no name is recorded. If your locale orders names differently, compose the name from its parts.
email​
String​

Email address of the Associate. Empty if it isn't known.

roles​
Array of AssociateRole​

Associate Roles that the Associate holds in the Business Unit they were read from, with the permissions each role grants.

Associate Role

A named set of permissions that the merchant assigns to Associates. Inputs refer to it by key. BusinessUnit.assignableRoles lists the Associate Roles you can assign.
key​
String​

User-defined unique identifier of the Associate Role.

name​
String​

Name of the Associate Role. Empty if no name is set.

permissions​
Array of AssociatePermission​

Permissions that the Associate Role grants, sorted and without duplicates. Empty if it grants none.

Can be ACCEPT_MY_QUOTES, ACCEPT_OTHERS_QUOTES, ADD_CHILD_UNITS, CREATE_APPROVAL_RULES, CREATE_MY_CARTS, CREATE_MY_ORDERS_FROM_MY_CARTS, CREATE_MY_ORDERS_FROM_MY_QUOTES, CREATE_MY_PAYMENT_METHODS, CREATE_MY_QUOTE_REQUESTS_FROM_MY_CARTS, CREATE_MY_SHOPPING_LISTS, CREATE_ORDERS_FROM_OTHERS_CARTS, CREATE_ORDERS_FROM_OTHERS_QUOTES, CREATE_OTHERS_CARTS, CREATE_OTHERS_PAYMENT_METHODS, CREATE_OTHERS_SHOPPING_LISTS, CREATE_QUOTE_REQUESTS_FROM_OTHERS_CARTS, DECLINE_MY_QUOTES, DECLINE_OTHERS_QUOTES, DELETE_MY_CARTS, DELETE_MY_PAYMENT_METHODS, DELETE_MY_SHOPPING_LISTS, DELETE_OTHERS_CARTS, DELETE_OTHERS_PAYMENT_METHODS, DELETE_OTHERS_SHOPPING_LISTS, REASSIGN_MY_QUOTES, REASSIGN_OTHERS_QUOTES, RENEGOTIATE_MY_QUOTES, RENEGOTIATE_OTHERS_QUOTES, UPDATE_APPROVAL_FLOWS, UPDATE_APPROVAL_RULES, UPDATE_ASSOCIATES, UPDATE_BUSINESS_UNIT_DETAILS, UPDATE_MY_CARTS, UPDATE_MY_ORDERS, UPDATE_MY_PAYMENT_METHODS, UPDATE_MY_QUOTE_REQUESTS, UPDATE_MY_SHOPPING_LISTS, UPDATE_OTHERS_CARTS, UPDATE_OTHERS_ORDERS, UPDATE_OTHERS_PAYMENT_METHODS, UPDATE_OTHERS_QUOTE_REQUESTS, UPDATE_OTHERS_SHOPPING_LISTS, UPDATE_PARENT_UNIT, VIEW_MY_CARTS, VIEW_MY_ORDERS, VIEW_MY_PAYMENT_METHODS, VIEW_MY_QUOTE_REQUESTS, VIEW_MY_QUOTES, VIEW_MY_SHOPPING_LISTS, VIEW_OTHERS_CARTS, VIEW_OTHERS_ORDERS, VIEW_OTHERS_PAYMENT_METHODS, VIEW_OTHERS_QUOTE_REQUESTS, VIEW_OTHERS_QUOTES, VIEW_OTHERS_SHOPPING_LISTS, or UNKNOWN​

Business Unit Type

Position of a Business Unit in the hierarchy.

COMPANY
Top-level Business Unit, without a parent unit.
DIVISION
Business Unit with a parent unit, which is a Company or another Division.

Business Unit Status

Status of a Business Unit, which controls whether it can be used in Carts, Orders, Quote Requests, and Quotes.

ACTIVE
The Business Unit can be used.
INACTIVE
The Business Unit can't be used. It isn't deleted.

Associate Permission

Permission granted by an Associate Role. The values match the Permission values of the platform, in upper snake case.
A permission is necessary but not always sufficient. For a specific resource, its availableActions field decides what the Associate can do with it.
ACCEPT_MY_QUOTES
The Associate can accept their own Quotes.
ACCEPT_OTHERS_QUOTES
The Associate can accept Quotes that belong to other Associates.
ADD_CHILD_UNITS
The Associate can create a child Business Unit.
CREATE_APPROVAL_RULES
The Associate can create Approval Rules.
CREATE_MY_CARTS
The Associate can create their own Carts.
CREATE_MY_ORDERS_FROM_MY_CARTS
The Associate can create Orders from their own Carts.
CREATE_MY_ORDERS_FROM_MY_QUOTES
The Associate can create Orders from their own Quotes.
CREATE_MY_PAYMENT_METHODS
The Associate can create their own payment methods.
CREATE_MY_QUOTE_REQUESTS_FROM_MY_CARTS
The Associate can create their own Quote Requests from their own Carts.
CREATE_MY_SHOPPING_LISTS
The Associate can create their own Shopping Lists.
CREATE_ORDERS_FROM_OTHERS_CARTS
The Associate can create Orders from Carts that belong to other Associates.
CREATE_ORDERS_FROM_OTHERS_QUOTES
The Associate can create Orders from Quotes that belong to other Associates.
CREATE_OTHERS_CARTS
The Associate can create Carts that belong to other Associates.
CREATE_OTHERS_PAYMENT_METHODS
The Associate can create payment methods that belong to other Associates.
CREATE_OTHERS_SHOPPING_LISTS
The Associate can create Shopping Lists that belong to other Associates.
CREATE_QUOTE_REQUESTS_FROM_OTHERS_CARTS
The Associate can create Quote Requests from Carts that belong to other Associates.
DECLINE_MY_QUOTES
The Associate can decline their own Quotes.
DECLINE_OTHERS_QUOTES
The Associate can decline Quotes that belong to other Associates.
DELETE_MY_CARTS
The Associate can delete their own Carts.
DELETE_MY_PAYMENT_METHODS
The Associate can delete their own payment methods.
DELETE_MY_SHOPPING_LISTS
The Associate can delete their own Shopping Lists.
DELETE_OTHERS_CARTS
The Associate can delete Carts that belong to other Associates.
DELETE_OTHERS_PAYMENT_METHODS
The Associate can delete payment methods that belong to other Associates.
DELETE_OTHERS_SHOPPING_LISTS
The Associate can delete Shopping Lists that belong to other Associates.
REASSIGN_MY_QUOTES
The Associate can reassign their own Quotes to a different Associate.
REASSIGN_OTHERS_QUOTES
The Associate can reassign Quotes that belong to other Associates.
RENEGOTIATE_MY_QUOTES
The Associate can renegotiate their own Quotes.
RENEGOTIATE_OTHERS_QUOTES
The Associate can renegotiate Quotes that belong to other Associates.
UPDATE_APPROVAL_FLOWS
The Associate can update Approval Flows, that is, approve or reject them.
UPDATE_APPROVAL_RULES
The Associate can update Approval Rules.
UPDATE_ASSOCIATES
The Associate can manage other Associates of the Business Unit.
UPDATE_BUSINESS_UNIT_DETAILS
The Associate can edit the details of the Business Unit, such as its name, contact email, and addresses.
UPDATE_MY_CARTS
The Associate can update their own Carts.
UPDATE_MY_ORDERS
The Associate can update their own Orders.
UPDATE_MY_PAYMENT_METHODS
The Associate can update their own payment methods.
UPDATE_MY_QUOTE_REQUESTS
The Associate can update their own Quote Requests.
UPDATE_MY_SHOPPING_LISTS
The Associate can update their own Shopping Lists.
UPDATE_OTHERS_CARTS
The Associate can update Carts that belong to other Associates.
UPDATE_OTHERS_ORDERS
The Associate can update Orders that belong to other Associates.
UPDATE_OTHERS_PAYMENT_METHODS
The Associate can update payment methods that belong to other Associates.
UPDATE_OTHERS_QUOTE_REQUESTS
The Associate can update Quote Requests that belong to other Associates.
UPDATE_OTHERS_SHOPPING_LISTS
The Associate can update Shopping Lists that belong to other Associates.
UPDATE_PARENT_UNIT
The Associate can assign a different parent unit to the Business Unit. The Associate also needs the `ADD_CHILD_UNITS` permission in the new parent unit.
VIEW_MY_CARTS
The Associate can view their own Carts.
VIEW_MY_ORDERS
The Associate can view their own Orders.
VIEW_MY_PAYMENT_METHODS
The Associate can view their own payment methods.
VIEW_MY_QUOTE_REQUESTS
The Associate can view their own Quote Requests.
VIEW_MY_QUOTES
The Associate can view their own Quotes.
VIEW_MY_SHOPPING_LISTS
The Associate can view their own Shopping Lists.
VIEW_OTHERS_CARTS
The Associate can view Carts that belong to other Associates.
VIEW_OTHERS_ORDERS
The Associate can view Orders that belong to other Associates.
VIEW_OTHERS_PAYMENT_METHODS
The Associate can view payment methods that belong to other Associates.
VIEW_OTHERS_QUOTE_REQUESTS
The Associate can view Quote Requests that belong to other Associates.
VIEW_OTHERS_QUOTES
The Associate can view Quotes that belong to other Associates.
VIEW_OTHERS_SHOPPING_LISTS
The Associate can view Shopping Lists that belong to other Associates.
UNKNOWN
A permission that this API doesn't model. Reported so that the permissions of a role are never under-counted. Not actionable.

Associate Role Inheritance Mode

Whether a role assignment is inherited by the child units of the Business Unit it is made on.

ENABLED
Child Business Units inherit the assignment.
DISABLED
Child Business Units don't inherit the assignment.

Business Unit Result

Returned by createBusinessUnit, changeBusinessUnitName, and setBusinessUnitContactEmail.
businessUnit​
BusinessUnit​
The Business Unit after the mutation. null if the mutation failed.
userErrors​
Array of UserError​

Errors that prevented the mutation. Empty on success.

Associate Result

Returned by addAssociate, updateAssociateRoles, and removeAssociate.
associate​
Associate​
The Associate after the mutation. null if the mutation failed, and after a successful removeAssociate.
userErrors​
Array of UserError​

Errors that prevented the mutation. Empty on success.

Quote Request

A request from a Buyer for the Seller to quote the contents of their Cart. Create one with requestQuote. For more information, see Quotes overview.
id​
ID​

Unique identifier of the Quote Request.

reference​
String​

Reference to show for the Quote Request: its key, or its platform ID if no key is set.

quoteRequestState​
QuoteRequestState​

Current state of the Quote Request.

Can be SUBMITTED, UNDER_REVIEW, ACCEPTED, REJECTED, CANCELLED, CLOSED, or UNKNOWN​
businessUnit​
BusinessUnit​
Business Unit the Quote Request belongs to. If the session can't read that Business Unit, this field returns an error, which makes the enclosing Quote Request null.
itemCount​
Int​

Total quantity of all lines.

total​
Money​
Total of the Quote Request, tax included. Same value as totals.grandTotal.
totals​
PriceTotals​
Price breakdown behind total, computed the same way as for a Cart and an Order. shipping is null if the Quote Request has no Shipping Method.
discounts​
Array of AppliedDiscount​
Every applied discount on the request, one entry per discount and target, its amount summed over the request: Product Discounts included where applied. The non-SHIPPING entries add up to totals.discountTotal.
createdAt​
DateTime​

Date and time (UTC) the Quote Request was created.

requestedBy​
Associate​
Buyer who created the Quote Request, with the Associate Roles they hold in the Business Unit. null if no Buyer is recorded. If the Buyer has left the Business Unit, roles is empty.
lines​
Array of QuoteLine​

Lines for which a Quote is requested, copied from the Cart when the request was created.

comment​
String​
Message from the Buyer included in the Quote Request. Set from message in RequestQuoteInput.
purchaseOrderNumber​
String​

Purchase order number that the Buyer set when requesting the Quote. It can't be changed afterward, and it's copied unchanged to the resulting Quote.

Quote Line

A line of a Quote Request or Quote. Represents a Line Item or a Custom Line Item.

sku​
String​

SKU of the Product Variant. Empty for a Custom Line Item.

productName​
String​

Name of the Product or Custom Line Item in the locale of the session.

quantity​
Int​

Number of units on the line.

isGift​
Boolean​
Whether this is a free Gift Line Item the platform added. Its Portion lists the gift discount that added it, which carries the same id as that discount's entry in discounts.
unitPriceBeforeDiscount​
Money​

One unit before any discount: the Line Item's price on the quote.

priceMode​
LinePriceMode​

How the Line Item's price was set; null for a custom line.

Can be PLATFORM, EXTERNAL_PRICE, or EXTERNAL_TOTAL​
discountedPrice​
LineItemDiscountedPrice​

One unit after its Product Discount, and the Product Discount behind it; null when none applies.

portions​
Array of Portion​

The Line Item's units grouped by what one unit costs after Cart Discounts, a seller's Direct Discounts included; at least one.

lineTotal​
Money​
What this Line Item costs after every discount: its Portions' unitPrice times quantity, added up. On an EXTERNAL_TOTAL Line Item it is the total the external system set instead.

Quote

An offer from the Seller in response to a Quote Request. The Buyer can accept, decline, or renegotiate it. For more information, see Quotes overview.
id​
ID​

Unique identifier of the Quote.

reference​
String​

Reference to show for the Quote: its key, or its platform ID if no key is set.

quoteState​
QuoteState​

Current state of the Quote.

Can be PENDING, DECLINED_FOR_RENEGOTIATION, RENEGOTIATION_ADDRESSED, ACCEPTED, DECLINED, WITHDRAWN, or UNKNOWN​
businessUnit​
BusinessUnit​
Business Unit the Quote belongs to. If the session can't read that Business Unit, this field returns an error, which makes the enclosing Quote null.
itemCount​
Int​

Total quantity of all lines.

total​
Money​
Amount the Buyer pays if they accept the Quote, tax included. Same value as totals.grandTotal.
totals​
PriceTotals​
Price breakdown behind total, computed the same way as for a Cart and an Order. shipping is null if the Quote has no Shipping Method.
discounts​
Array of AppliedDiscount​
Every applied discount on the quote, one entry per discount and target, its amount summed over the quote: Product Discounts included where applied, and a seller's Direct Discounts. The non-SHIPPING entries add up to totals.discountTotal.
createdAt​
DateTime​

Date and time (UTC) the Quote was created.

expiresAt​
DateTime​
Date and time (UTC) the Quote expires. null if the Seller set no expiry.
After this time, the Quote can't be acted on and availableActions is empty. quoteState doesn't change when the Quote expires, so a PENDING Quote can be expired.
requestedBy​
Associate​
Buyer who requested the Quote, with the Associate Roles they hold in the Business Unit. null if no Buyer is recorded. If the Buyer has left the Business Unit, roles is empty.
lines​
Array of QuoteLine​

Lines of the Quote.

buyerComment​
String​

Latest message from the Buyer: the message sent with a renegotiation request, or the reason given when declining.

sellerComment​
String​

Message from the Seller included in the Quote.

purchaseOrderNumber​
String​

Purchase order number copied unchanged from the Quote Request. It can't be changed.

availableActions​
Array of QuoteAction​
Actions that the current Associate can take on the Quote, based on their permissions for their own Quotes or for Quotes of other Associates. Empty unless the Quote is PENDING and hasn't expired. acceptQuote, declineQuote, and renegotiateQuote refuse an action that isn't listed here.
Can be ACCEPT, RENEGOTIATE, or DECLINE​

Quote Request Connection

Paginated result of quoteRequests.
edges​
Array of QuoteRequestEdge​

Quote Requests on this page, with their cursors.

nodes​
Array of QuoteRequest​
Quote Requests on this page, in the same order as edges.
pageInfo​
PageInfo​

Information for getting the next or previous page.

totalCount​
Int​

Total number of Quote Requests that match the query, across all pages.

Quote Request Edge

Entry in a QuoteRequestConnection.
node​
QuoteRequest​

The Quote Request.

cursor​
String​
Opaque cursor of this item. Pass it as after to get the items that follow it.

Quote Connection

Paginated result of quotes.
edges​
Array of QuoteEdge​

Quotes on this page, with their cursors.

nodes​
Array of Quote​
Quotes on this page, in the same order as edges.
pageInfo​
PageInfo​

Information for getting the next or previous page.

totalCount​
Int​

Total number of Quotes that match the query, across all pages.

Quote Edge

Entry in a QuoteConnection.
node​
Quote​

The Quote.

cursor​
String​
Opaque cursor of this item. Pass it as after to get the items that follow it.

Quote Request State

State of a Quote Request in the negotiation process.

SUBMITTED
The Buyer submitted the Quote Request, and the Seller hasn't accepted or rejected it yet. Initial state of a Quote Request.
UNDER_REVIEW
Reserved state. A Quote Request can report it, but no operation in this API sets it.
ACCEPTED
The Seller accepted the Quote Request and is preparing a Quote for the Buyer.
REJECTED
The Seller rejected the Quote Request, which ends the negotiation.
CANCELLED
The Buyer withdrew the Quote Request, for example with `cancelQuoteRequest`.
CLOSED
Final state. The Seller accepted the Quote Request, and no further action is possible.
UNKNOWN
A state that this API doesn't model. The Quote Request is still listed. Treat it as read-only.

Quote State

Negotiation state of a Quote. Expiry isn't a state, see Quote.expiresAt.
PENDING
The Seller sent the Quote, and the Buyer hasn't replied yet. Only a `PENDING` Quote can be accepted, declined, or renegotiated.
DECLINED_FOR_RENEGOTIATION
The Buyer declined the Quote and asked to renegotiate it. The Seller hasn't answered yet.
RENEGOTIATION_ADDRESSED
The Seller answered the renegotiation request with a new Quote. This Quote offers no actions.
ACCEPTED
The Buyer accepted the Quote. `acceptQuote` also creates an Order from it in the same step.
DECLINED
The Buyer declined the Quote. `buyerComment` holds the reason, if the Buyer gave one.
WITHDRAWN
The Seller withdrew the Quote before the Buyer accepted it.
UNKNOWN
A state that this API doesn't model. The Quote is still listed and offers no `availableActions`. Treat it as read-only.

Quote Action

Action on a Quote that Quote.availableActions can offer.
ACCEPT
Accept the Quote with `acceptQuote`, which also creates an Order from it. Offered only if the Associate has permission both to accept the Quote and to create an Order from it.
RENEGOTIATE
Ask the Seller to renegotiate the Quote with `renegotiateQuote`.
DECLINE
Decline the Quote with `declineQuote`. If `RENEGOTIATE` isn't offered, decline without a `reason`.

Quote Request Result

Returned by requestQuote and cancelQuoteRequest.
quoteRequest​
QuoteRequest​
The Quote Request after the mutation. null if the mutation failed, except for QUOTE_REQUEST_NOT_ACTIONABLE, which returns the unchanged Quote Request.
userErrors​
Array of UserError​

Errors that prevented the mutation. Empty on success.

Quote Result

Returned by acceptQuote, declineQuote, and renegotiateQuote.
quote​
Quote​
The Quote after the mutation. If a check before the write refuses the mutation, for example because of the Quote's state or expiry, or a permission that availableActions reflects, this is the unchanged Quote. If the platform refuses the write, quote is null. For example, declineQuote with a reason but without the permission to renegotiate returns FORBIDDEN_ACTION and a null Quote.
order​
Order​
Order created from the Quote. Set only by a successful acceptQuote.
userErrors​
Array of UserError​

Errors that prevented the mutation. Empty on success.

Approval Flow

The approval process of an Order that matched one or more Approval Rules. Created when the Order is placed. For more information, see Approval Flows.
id​
ID​

Unique identifier of the Approval Flow.

order​
Order​
Order that needs approval. null if the current Associate isn't allowed to view the Order, for example an Order of another Associate without the VIEW_OTHERS_ORDERS permission. The Approval Flow itself is still returned.
orderReference​
String​

Reference of the Order: its order number, or its platform ID if it has none.

approvalState​
ApprovalState​

Current state of the Approval Flow.

Can be PENDING, APPROVED, or REJECTED​
total​
Money​
Total of the Order under review. Where prices exclude tax, this is the total before tax. null under the same conditions as order.
requestedBy​
Associate​
Associate who placed the Order, with the Associate Roles they hold in the Business Unit. If the Order can't be read, id holds the Order's id, and the name fields and roles are empty. If the Associate has left the Business Unit, the name fields and roles are empty.
createdAt​
DateTime​

Date and time (UTC) the Approval Flow was created.

matchedRules​
Array of ApprovalRule​

Approval Rules that the Order matched. All of them must be satisfied. Each rule has its own approver tiers.

eligibleApproverRoles​
Array of AssociateRole​

Associate Roles that can approve, across all matched Approval Rules.

pendingApproverRoles​
Array of AssociateRole​

Associate Roles still required for approval, across all remaining tiers.

currentTierPendingApproverRoles​
Array of AssociateRole​

Associate Roles required by the currently active tiers. More than one tier can be active at once, one for each matched Approval Rule.

decisions​
Array of ApprovalDecision​

Approvals recorded so far, oldest first.

rejection​
ApprovalRejection​
Rejection of the Approval Flow. null unless approvalState is REJECTED.
availableActions​
Array of ApprovalFlowAction​
Actions that the current Associate can take on the Approval Flow. Empty unless the flow is PENDING, the Associate has the UPDATE_APPROVAL_FLOWS permission, and they hold a role in currentTierPendingApproverRoles.
Can be APPROVE, or REJECT​

Approval Rule

A rule that defines which Orders of a Business Unit need approval, and which Associate Roles approve them. For more information, see Approval Rules.
id​
ID​

Unique identifier of the Approval Rule.

key​
String​
User-defined identifier of the Approval Rule, unique within the Business Unit. null if no key is set.
name​
String​

Name of the Approval Rule.

description​
String​

Description of the Approval Rule.

approvalRuleState​
ApprovalRuleState​

State of the Approval Rule.

Can be ACTIVE, or INACTIVE​
conditions​
Array of ApprovalCondition​
Typed conditions of the Approval Rule. Complete only if conditionsFullyTyped is true.
predicate​
String​
Stored Order Predicate of the Approval Rule, read-only. Read it when conditionsFullyTyped is false. To change the conditions, set conditions in the input instead.
conditionsFullyTyped​
Boolean​
Whether conditions represents the whole predicate.
If false, the Approval Rule contains clauses that this API can't express. Don't present such a rule as unconditional, and don't replace its conditions.
approverTiers​
Array of ApproverTier​

Approver hierarchy of the Approval Rule, in tier order.

requesterRoles​
Array of AssociateRole​

Associate Roles whose Orders the Approval Rule applies to.

Approval Condition

A typed condition of an Approval Rule. An Order must meet all conditions of an Approval Rule for the rule to match.

field​
ApprovalConditionField​

What the condition tests.

Can be ORDER_TOTAL, ORDER_CURRENCY, or SHIPPING_COUNTRY​
operator​
ApprovalConditionOperator​

How the condition compares the Order value.

Can be GT, GTE, LT, LTE, or EQ​
threshold​
Money​
Threshold amount, in the currency it was set in. Set only for ORDER_TOTAL.
code​
String​
Currency code (ISO 4217) for ORDER_CURRENCY, or country code (ISO 3166-1 alpha-2) for SHIPPING_COUNTRY. null for ORDER_TOTAL.

Approver Tier

A tier of the approver hierarchy of an Approval Rule. Tiers are approved in order. Within a tier, every group must be satisfied. For example, to require approval from both a finance role and a legal role, use two groups in one tier.

Approvers are Associate Roles, not individual Associates. A tier has no name. Identify it by order.
order​
Int​
Position of the tier in the hierarchy, starting at 1.
groups​
Array of ApproverGroup​

Groups that must all be satisfied to approve the tier.

Approver Group

A group of Associate Roles within an approver tier. An approval from an Associate who holds any one of these roles satisfies the group.

roles​
Array of AssociateRole​

Associate Roles in the group.

Approval Decision

An approval recorded on an Approval Flow. The tier that the approval satisfied isn't recorded. decidedBy.roles lists the Associate Roles of the approver.
decidedBy​
Associate​

Associate who approved.

decidedAt​
DateTime​

Date and time (UTC) of the approval.

Approval Rejection

Recorded when an approver rejects an Approval Flow. A single rejection rejects the whole Approval Flow.

rejectedBy​
Associate​

Associate who rejected the Approval Flow.

rejectedAt​
DateTime​

Date and time (UTC) the Approval Flow was rejected.

reason​
String​

Reason given for the rejection.

Approval Flow Connection

Paginated result of approvals.
edges​
Array of ApprovalFlowEdge​

Approval Flows on this page, with their cursors.

nodes​
Array of ApprovalFlow​
Approval Flows on this page, in the same order as edges.
pageInfo​
PageInfo​

Information for getting the next or previous page.

totalCount​
Int​

Total number of Approval Flows that match the query, across all pages.

Approval Flow Edge

Entry in an ApprovalFlowConnection.
node​
ApprovalFlow​

The Approval Flow.

cursor​
String​
Opaque cursor of this item. Pass it as after to get the items that follow it.

Approval Rule Connection

Paginated result of approvalRules.
edges​
Array of ApprovalRuleEdge​

Approval Rules on this page, with their cursors.

nodes​
Array of ApprovalRule​
Approval Rules on this page, in the same order as edges.
pageInfo​
PageInfo​

Information for getting the next or previous page.

totalCount​
Int​

Total number of Approval Rules that match the query, across all pages.

Approval Rule Edge

Entry in an ApprovalRuleConnection.
node​
ApprovalRule​

The Approval Rule.

cursor​
String​
Opaque cursor of this item. Pass it as after to get the items that follow it.

Approval State

Decision state of an Approval Flow.

PENDING
The Approval Flow isn't fully approved or rejected yet.
APPROVED
All approvers required by the matched Approval Rules have approved.
REJECTED
An approver rejected the Approval Flow.

Approval Flow Action

Action on an Approval Flow that ApprovalFlow.availableActions can offer.
APPROVE
Approve the Order with `approveOrder`.
REJECT
Reject the Order with `rejectOrder`.

Approval Rule State

Whether an Approval Rule is in effect.

ACTIVE
The Approval Rule is matched against Orders.
INACTIVE
The Approval Rule isn't matched against Orders.

Approval Condition Field

Order value that a typed approval condition tests.

ORDER_TOTAL
Total of the Order, compared against a threshold in a given currency.
ORDER_CURRENCY
Currency of the Order.
SHIPPING_COUNTRY
Country of the Order. The condition tests the `country` field of the [Order](https://docs.commercetools.com/api/projects/orders#ctp:api:type:Order), which is used for price selection, not the country of the shipping address.

Approval Condition Operator

Comparison operator of an approval condition. Which operators a field accepts is listed on ApprovalConditionInput.
GT
Greater than.
GTE
Greater than or equal to.
LT
Less than.
LTE
Less than or equal to.
EQ
Equal to.

Approval Flow Result

Returned by approveOrder and rejectOrder.
approvalFlow​
ApprovalFlow​
The Approval Flow after the mutation. null if the mutation failed.
userErrors​
Array of UserError​

Errors that prevented the mutation. Empty on success.

Approval Rule Result

Returned by createApprovalRule, updateApprovalRule, and setApprovalRuleActive.
approvalRule​
ApprovalRule​
The Approval Rule after the mutation. null if the mutation failed.
userErrors​
Array of UserError​

Errors that prevented the mutation. Empty on success.

Input types

Create Business Unit Input

New Division under an existing Business Unit.

The new Division takes its Stores from the parent unit. The current Associate is added to it with the roles they hold in the parent unit, so the Division never grants them more than the parent does. The Division is created with the status ACTIVE.
key​
String​
User-defined unique identifier of the new Business Unit. A key that is already in use is refused with BUSINESS_UNIT_KEY_EXISTS.
name​
String​

Name of the new Business Unit.

parentUnitKey​
String​
Key of the parent Company or Division. The current Associate must hold a role there that has the ADD_CHILD_UNITS permission. Otherwise, the mutation is refused with NOT_AUTHORIZED.
contactEmail​
String​

Email address of the new Business Unit.

Add Associate Input

New Associate of the active Business Unit.

email​
String​

Email address of the Customer to add. The Customer must already have an account in the Project.

roleKeys​
Array of String​
Keys of the Associate Roles to assign. An unknown key is refused with ASSOCIATE_ROLE_NOT_FOUND.
inheritance​
AssociateRoleInheritanceMode​
Inheritance mode for every role assigned here. If omitted, each assignment gets the platform default, DISABLED. See AssociateRoleAssignmentDraft.
Can be ENABLED, or DISABLED​

Update Associate Roles Input

New role assignment of an existing Associate.

associateId​
ID​

ID of the Associate to update. The Business Unit is taken from this ID, so an Associate of a child unit is updated in that child unit.

roleKeys​
Array of String​
Keys of the Associate Roles that the Associate holds after the update. Replaces all current roles. An unknown key is refused with ASSOCIATE_ROLE_NOT_FOUND.
inheritance​
AssociateRoleInheritanceMode​
Inheritance mode for every role assigned here. If omitted, a role the Associate already holds keeps its current mode, and a newly assigned role gets the platform default, DISABLED.
Can be ENABLED, or DISABLED​

Quote Request Filter

Filters for quoteRequests. A Quote Request must match every field you set.
query​
String​
Matches a Quote Request whose reference equals this value. The match is exact, not a substring search.
quoteRequestState​
Array of QuoteRequestState​
Matches Quote Requests in any of these states. UNKNOWN matches nothing.
Can be SUBMITTED, UNDER_REVIEW, ACCEPTED, REJECTED, CANCELLED, CLOSED, or UNKNOWN​

Quote Filter

Filters for quotes. A Quote must match every field you set.
query​
String​
Matches a Quote whose reference equals this value. The match is exact, not a substring search.
quoteState​
Array of QuoteState​
Matches Quotes in any of these states. UNKNOWN matches nothing.
Can be PENDING, DECLINED_FOR_RENEGOTIATION, RENEGOTIATION_ADDRESSED, ACCEPTED, DECLINED, WITHDRAWN, or UNKNOWN​

Request Quote Input

Buyer details for a new Quote Request.

message​
String​
Message to the Seller. Stored as the comment of the Quote Request.
purchaseOrderNumber​
String​

Purchase order number of the Buyer for this request. It can't be changed after the request is created.

Renegotiate Quote Input

Renegotiation request for a Quote.

quoteId​
ID​

ID of the Quote to renegotiate.

message​
String​
Message to the Seller that explains what to change. Stored as the buyerComment of the Quote.

Approval Flow Filter

Filters for approvals.
approvalState​
Array of ApprovalState​

Matches Approval Flows in any of these states.

Can be PENDING, APPROVED, or REJECTED​

Approval Rule Filter

Filters for approvalRules.
approvalRuleState​
Array of ApprovalRuleState​

Matches Approval Rules in any of these states.

Can be ACTIVE, or INACTIVE​

Create Approval Rule Input

Definition of a new Approval Rule.

key​
String​

User-defined identifier of the Approval Rule, unique within the Business Unit.

name​
String​

Name of the Approval Rule.

description​
String​

Description of the Approval Rule.

conditions​
Array of ApprovalConditionInput​
Conditions that an Order must meet for the Approval Rule to apply. An empty list is refused with CONDITION_NOT_SUPPORTED.
approverTiers​
Array of ApproverTierInput​
Approver hierarchy, in tier order. An empty list is refused with APPROVER_TIERS_REQUIRED.
requesterRoleKeys​
Array of String​
Keys of the Associate Roles whose Orders the Approval Rule applies to. An unknown key is refused with ASSOCIATE_ROLE_NOT_FOUND.
approvalRuleState​
ApprovalRuleState​
Initial state of the Approval Rule. Default: ACTIVE.
Can be ACTIVE, or INACTIVE​

Update Approval Rule Input

Changes to an Approval Rule. Only the fields you set change. Omitted and null fields keep their current value. To change the state, use setApprovalRuleActive.
Setting conditions replaces the whole predicate of the Approval Rule. For a rule whose conditionsFullyTyped is false, this is refused with CONDITION_NOT_SUPPORTED.
id​
ID​

ID of the Approval Rule to update.

key​
String​

New key of the Approval Rule.

name​
String​

New name of the Approval Rule.

description​
String​

New description of the Approval Rule.

conditions​
Array of ApprovalConditionInput​
New conditions, which replace all current conditions. Validated the same way as in CreateApprovalRuleInput.
approverTiers​
Array of ApproverTierInput​

New approver hierarchy, which replaces the current one.

requesterRoleKeys​
Array of String​

New requester role keys, which replace the current ones.

Approval Condition Input

A condition to set on an Approval Rule. Set the values that field requires:
  • ORDER_TOTAL: amountInMinorUnits and currency, with any operator.
  • ORDER_CURRENCY or SHIPPING_COUNTRY: code, with the EQ operator.
Any other combination is refused with CONDITION_NOT_SUPPORTED. The field of the error points to the value that is wrong, except for an extra value on ORDER_CURRENCY or SHIPPING_COUNTRY, where it points to the condition's field.
field​
ApprovalConditionField​

What the condition tests.

Can be ORDER_TOTAL, ORDER_CURRENCY, or SHIPPING_COUNTRY​
operator​
ApprovalConditionOperator​

How the condition compares the Order value.

Can be GT, GTE, LT, LTE, or EQ​
amountInMinorUnits​
Int​
Threshold in the minor units of currency, for example 500000 for 5,000.00 GBP. Required for ORDER_TOTAL, and must be a non-negative whole number. Not allowed for other fields.
currency​
String​
Currency code (ISO 4217) of the threshold. Required for ORDER_TOTAL, and the condition then matches only Orders in this currency. Not allowed for other fields.
code​
String​
Currency code (ISO 4217) for ORDER_CURRENCY, or country code (ISO 3166-1 alpha-2) for SHIPPING_COUNTRY. Must contain letters only. Not allowed for ORDER_TOTAL.

Approver Tier Input

Approver tier to set on an Approval Rule. See ApproverTier for when a tier is satisfied. For a tier that any of several roles can approve, pass a single group.
groups​
Array of ApproverGroupInput​
Groups of the tier. An empty list is refused with APPROVER_TIERS_REQUIRED.

Approver Group Input

Group of Associate Roles to set in an approver tier. See ApproverGroup for when a group is satisfied.
roleKeys​
Array of String​
Keys of the Associate Roles in the group. An empty list is refused with APPROVER_TIERS_REQUIRED, and an unknown key with ASSOCIATE_ROLE_NOT_FOUND.