Skip to main content

Wholesale Quotations

This guide explains how to interact with Geins for handling wholesale quotations.

Introduction​

A Buyer​

A buyer is an individual or entity within an account that purchases goods or services from a merchant. A buyer operates either on behalf of themselves or as authorized representatives of an account.

Each buyer is also linked to a user account that grants access to all their assigned quotations.

The main focus of a buyer is to review and manage quotations created by the merchant.

A Quotation​

A quotation is a custom offer created by the merchant for an account. The quotation defines a collection of items, prices and terms that is specific to each quotation.

Items and prices within a quotation are immutable, eg cannot be changed. If changes are required, a new quotation must be created while the old one is canceled.

Quotations can be targeted to all buyers within an account or just a subset of specific buyers.

Quotation Life Cycle​

After a merchant creates a quotation, it is handed over to the buyer. The buyer reviews the quotation and decides whether to accept or reject it. These actions are accomplished through calls to the Merchant API.

A quotation can have a number of different statuses that it passes through during its lifetime. However, it can have any given status only once. Reverting to a previous status is not allowed.

note

For a quotation to continue its lifecycle and become an actual order, it must be accepted by the buyer. If rejected, the quotation becomes invalid.

Buyer​

Authentication​

To view and take action on a quotation, a buyer must log in with a user account that belongs to the same wholesale account as the quotation. Additionally, the quotation must be assigned to the buyer by the merchant.

note

Quotations can only be viewed and edited from logged in users with the proper access.

Endpoints Overview​

  1. List Quotations: Retrieve all quotations
  2. Get Quotation: Retrieve a specific quotation
  3. Set Status on Quotation: Accept or Reject a specific quotation

Endpoints​

Listing Quotations​

After logging in, a buyer can retrieve a list of all available quotations using the listQuotations query. This query also allows filtering by status.

tip

Use the listQuotations endpoint to display summaries of pending or reviewed quotations in the buyer's dashboard.

# Example query to list quotations with a specific status
query ListQuotations {
  listQuotations(status: PENDING) {
    publicQuotationId
    totalPriceExVat
    status
    validTo
  }
}

Get Quotation​

To see the specifics of a single quotation, the getQuotation endpoint can be used. A quotation is identified by its public ID.

tip

getQuotation and listQuotations offer the same breadth of fields. Be sure to limit your query to only include the data you actually need.

# Example query to get a specific quotation by its public ID
query GetQuotation {
  getQuotation(quotationId: "de5c5a54-295e-4491-8290-1ecd21698c2d") {
    validTo
    totalPriceExVat
    merchantMessage
    status
    items {
      lineNumber
      skuId
      skuName
      quantity
      sellingPriceExVat
      discountAmount
      discountPercent
      articleNumber
      primaryImage
    }
  }
}

Set Quotation Status​

When the buyer is ready to make a decision about a pending quotation, they can call the setQuotationStatus endpoint to finalize their decision. This endpoint accepts the public ID of a quotation and a status of either ACCEPT or REJECT.

Optionally, a message from the buyer to the merchant can also be included.

caution

Setting a status cannot be reverted. Ensure the decision is final before accepting or rejecting.

note

Only quotations with status PENDING can be modified.

# Example mutation to set the status of a quotation
mutation SetQuotationStatus {
  setQuotationStatus(
    quotationId: "de5c5a54-295e-4491-8290-1ecd21698c2d",
    status: ACCEPT,
    message: "Please deliver before end of year."
  )
}