• Last edited on: 30 July 2024

Open Buy API Reference

The Open Buy API is designed to provide a faster, standard, and secure interface for searching and purchasing items in real-time for all suppliers.

Introduction

The Open Buy API is designed to provide a faster, standard, and secure interface for searching and purchasing items in real-time for all suppliers. It is designed to be simple and follows the common patterns that most eCommerce APIs provide.

The four core concepts in the Open Buy API include:

  • Authentication
  • Search
  • Detail
  • Checkout

For information on how the Open Buy API affects customers and buyers, see Open Buy API for Buyers.

Download our Open Buy schema file for use in Postman or another OpenAPI 3.0 compatible tool, or view the schema file directly in an online viewer like ReDoc.

Authentication methods

The Open Buy API may be authenticated through:

  • Username and password (similar to cXML identity/secret pair)

  • OAuth

Actions

The Open Buy API allows you to:

API Verb Path Action Description
Authentication POST /authentication/v1.0.0 authenticate Authentication with supplier site
Search POST /search/v1.0.0 search Retrieve item data based on a search query
Detail POST /detail/v1.0.0 detail Retrieve item data for a specific item for detailed review
Checkout POST /checkout/v1.0.0 checkout Retrieve item data for purchase

    Authentication

    API Verb Path Action Description
    Authentication POST /authentication/v1.0.0 authenticate Authentication with supplier site

    Example authentication request

    {
    	"credentials": "423j23j2j334l4s04",
    	"email": "email@coupa.com"
    }

    Responses

    Code Description
    200

    Token successfully retrieved

    
    {
    "token": "ABC12345"
    }

     

    400

    Invalid request parameters; we were unable to attempt retrieval.

    401

    Unauthorized

    500

    Service error during request. Please retry after sometime

    Search

    API Verb Path Action Description
    Search POST /search/v1.0.0 search Retrieve item data based on a search query

    Parameters

    Element Description Required Field? Unique? Allowable Value Data Type
    query The search query yes no any string
    page_number Page number for results no no any number

    Responses

    Code Description
    200

    Search results successfully retrieved

    
    {
    	"count": 0,
    	"total_count": 0,
    	"results": [
    		{
    			"source_part_num": 12345,
    			"title": "Leather Gloves - XL",
    			"url": "https://localhost/image",
    			"price": 100,
    			"currency": "USD",
    			"uom": "EA"
    		}
    	]
    }
    400

    Invalid request parameters; we were unable to attempt retrieval.

    401

    Unauthorized

    500

    Service error during request. Please retry after sometime

    Detail

    API Verb Path Action Description
    Detail POST /detail/v1.0.0 detail Retrieve item data for a specific item for detailed review

    Parameters

    Element Description Required Field? Unique? Allowable Value Data Type
    item_id The unique item ID yes no any string

    Responses

    Code Description
    200

    Item successfully retrieved

    
    {
    	"source_part_num": 12345,
    	"title": "Leather Gloves - XL",
    	"url": "https://localhost/image",
    	"price": 100,
    	"currency": "USD",
    	"uom": "EA"
    }
    400

    Invalid request parameters; we were unable to attempt retrieval.

    401

    Unauthorized

    500

    Service error during request. Please retry after sometime

    Checkout

    API Verb Path Action Description
    Checkout POST /checkout/v1.0.0 checkout Retrieve item data for purchase

    Parameters

    Element Description Required Field? Unique? Allowable Value Data Type
    item_id The unique item ID yes yes any string
    quantity Quantity no no any string

    Responses

    Code Description
    200

    Item successfully retrieved

    
    {
    	"source_part_num": 12345,
    	"title": "Leather Gloves - XL",
    	"url": "https://localhost/image",
    	"price": 100,
    	"currency": "USD",
    	"uom": "EA"
    }
    400

    Invalid request parameters; we were unable to attempt retrieval.

    401

    Unauthorized

    500

    Service error during request. Please retry after sometime

    Open Buy API schema

    Authentication Request

    The credentials and email to retrieve an access token.

    Element Description Required Field? Data Type
    credentials

    Supplier-specific string to authorize the session. Examples include a refresh token, user and password, or an authorization key.

    no string
    email

    Email of user

    no string

    Authentication Result

    The result of a request for authentication

    Element Description Required Field? Data Type
    token

    The bearer token

    no string

    Extra Item Details

    Name value pairs

    Element Description Required Field? Data Type
    name Name no string
    value Value no string

    Search Results

    The result of a search request

    Element Description Required Field? Data Type
    count

    Count of search

    yes integer
    total_count Approximate total number in catalog no integer
    results Results no

    Item Result (see table below)

    Item Result

    Thee result of a request for item data

    Element Description Required Field? Data Type
    item_id

    Unique item id

    no string
    source_part_num

    The supplier part number

    no string
    title string

    The title of the item

    no string
    type string

    Item Type (item, group). Group represents a parent of purchasable items.

    no string
    image

    A URL to the item image

    no string
    thumbnail

    Thumbnail of product

    no string
    price

    Price

    no number
    currency

    Currency

    no string
    listPrice

    List price

    no number
    uom

    Price

    no string
    summary

    Detail description about the item

    no string
    manufacturer_name

    Manufacturer name

    no string
    manufacturer_part_num

    Manufacturer part number

    no string
    source_part_auxiliary_id

    Supplier aux part number

    no string
    unspsc

    UNSPSC

    no string
    leadtime

    Lead time

    no string
    min_order_quantity

    Minimal order quantity

    no number
    max_order_quantity Max order quantity no number
    order_increment_quantity

    Order increment number

    no number
    quantity

    Quantity for checkout

    no number
    tableDetails Columns to display if shown in a table no string
    details Details no Extra Item Details (see table above)
    detaillinks Detail Links no Extra Item Details (see table above)
    detailimages Detail Images no Extra Item Details (see table above)