Skip to main content
Knowledge Base content is available to TradeCentric customers. To access all articles and videos, log in using single sign-on from Portal.

PunchOut: Standard JSON payload for return cart

  • Updated

The return cart payload returns cart data from your eCommerce platform to the TradeCentric platform so that we can return the cart to the buyer's eProcurement system. For standard integrations that receive JSON payloads, we accept the return cart payload in our standard JSON format.

This article describes the standard JSON format to use for this payload.

Note: Send this payload to the TradeCentric platform as a server-to-server POST request, using the return URL in the session request payload that we sent. This URL includes the unique punchout session identifier.

Jump to:

Request payload (to TradeCentric)
Response payload (from TradeCentric)

 

Request payload (to TradeCentric)

The code block below shows an example return cart payload in our standard JSON format:

JSON
HTTP POST
Return cart
{
  "body": {
    "total": 142.09,
    "currency": "USD",
    "data": {
      "edit_mode": 1,
      "shipping": 10.00,
      "shipping_description": "Shipping estimate - FedEx 2Day",
      "tax": 8.64,
      "tax_description": "Sales tax - 7% Tennessee"
    },
    "items": [
      {
        "quantity": 3,
        "supplierid": "45L017",
        "supplierauxid": "CART12-ITEM123",
        "description": "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant",
        "unitprice": 41.15,
        "currency": "USD",
        "uom": "EA",
        "classification": "56101720",
        "classdomain": "UNSPSC",
        "language": "en-US",
        "data": {
          "manufacturer": "Kissler & Co. Inc.",
          "manufacturer_id": "77-1206",
          "lead_time": 3,
          "image_url": "https://www.mystorefront.com/images/product/77-1206.jpg",
          "is_catchweight": 0
        }
      }
    ]
  }
}

 

Request field details

A standard JSON return cart payload has a body object that contains cart values, an optional data object, and an items array. The subsections below explain each structure and its fields.

 

Body

Provides the cart value and item data, which are described in the subsections below

 

Total value

Required Max use: 1 each

Provides the total value of the entire cart

Example
"body": {
  "total": 142.09,
  "currency": "USD"
}
Total value field breakdown
  • total
    Total cart value

    Required Type: Number

    Provides the total value of all items in the cart, plus any estimated tax or shipping values

    Example: 142.09

    Note: We require this field for data reporting only. All eProcurement systems recalculate the total value once they receive the return cart payload.

  • currency
    Cart currency

    Required Format: ISO 4217

    Specifies the currency for the total value

    Example: "USD"

 

Data

Optional Max use: 1

Provides any additional cart attributes, which may vary depending on the integration's requirements

Note: Often, suppliers send tax and shipping values and descriptions in this object. Most eProcurement systems only accept the tax, shipping, currency, and total fields.

Example
"data": {
  "edit_mode": 1,
  "shipping": 10.00,
  "shipping_description": "Shipping estimate - FedEx 2Day",
  "tax": 8.64,
  "tax_description": "Sales tax - 7% Tennessee"
}
Data field breakdown
  • edit_mode
    Edit cart setting

    Optional Accepted values: 0, 1

    Indicates whether the buyer can submit an edit request to modify the cart

    Values: 0 = not allowed, 1 = allowed

  • shipping
    Shipping value

    Optional Type: Number

    Provides an estimated shipping value for the cart

    Example: 10.00

    Note: This value doesn’t represent the final, agreed shipping amount. The buyer can still edit the cart or change the shipping destination.

  • shipping_description
    Shipping description

    Optional Type: String

    Provides a description for the shipping value

    Example: "Shipping estimate - FedEx 2Day"

  • tax
    Tax value

    Optional Type: Number

    Provides an estimated tax value for the cart

    Example: 8.64

    Note: This value doesn’t represent the final, agreed tax amount. The buyer can still edit the cart or change the shipping destination.

  • tax_description
    Tax description

    Optional Type: String

    Provides a description for the tax value

    Example: "Sales tax - 7% Tennessee"

 

Items

Required Max use: Many

Provides details about each of the line items in the cart

Note: Repeat the object for each line item, using curly braces to group the item's fields.

Example
"items": [
  {
    "quantity": 3,
    "supplierid": "45L017",
    "supplierauxid": "CART12-ITEM123",
    "description": "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant",
    "unitprice": 41.15,
    "currency": "USD",
    "uom": "EA",
    "classification": "56101720",
    "classdomain": "UNSPSC",
    "language": "en-US",
    "data": {
      "manufacturer": "Kissler & Co. Inc.",
      "manufacturer_id": "77-1206",
      "lead_time": 3,
      "image_url": "https://www.mystorefront.com/images/product/77-1206.jpg",
      "is_catchweight": 0
    }
  }
]
Items field breakdown
  • quantity
    Quantity

    Required Type: Number

    Provides the item quantity

    Example: 3

  • supplierid
    Supplier part identifier

    Required Type: String

    Provides the item identifier, such as a part number or Stock Keeping Unit (SKU)

    Example: "45L017"

  • supplierauxid
    Supplier auxiliary identifier

    Required for purchase order conversion Type: String

    Provides a unique identifier using either an additional item identifier, such as for a specific color or packaging option, or a database identifier for the item within the cart object

    Example: "CART12-ITEM123"

  • description
    Product description

    Required Type: String

    Provides a readable item description 

    Example: "Low Arc Kitchen Faucet: Dominion Faucets, Silver, Chrome Finish, 1.75 gpm Flow Rate, CEC Compliant"

  • unitprice
    Unit price

    Required Type: Number

    Provides the price of one unit of the item after applying any discounts or special pricing

    Example: 41.15

  • currency
    Line item currency

    Required Format: ISO 4217

    Specifies the currency for the unit price value

    Example: "USD"

  • uom
    Unit of measure

    Required Format: Varies by supplier

    Provides the item unit of measure, which we'll map to the buyer's accepted format before sending the final payload

    Example: "EA"

  • classification
    Classification code

    Required Format: Varies by supplier

    Provides the item classification code, which we'll map to the buyer's accepted format before sending the final payload

    Example: "56101720"

  • classdomain
    Classification type

    Optional Type: String

    Specifies the type of classification code provided

    Example: "UNSPSC" =United Nations Standard Products and Services Code (UNSPSC)

  • language
    Description language

    Optional Format: ISO 639-ISO 3166

    Specifies the language used for the item description

    Example: "en-US"

  • data
    Additional item data

    Optional

    Groups additional item attributes, which may vary depending on the integration's requirements

    Note: Depending on the buyer's requirements, we may deliver additional item details to the eProcurement system using the description field. For example, we typically move item color or other variation details to that field.

    • manufacturer Manufacturer name

      Optional Type: String

      Provides the manufacturer's name

      Example: "Kissler & Co. Inc."

    • manufacturer_id Manufacturer part identifier

      Optional Type: String

      Provides the manufacturer's identifier for the item

      Example: "77-1206"

    • lead_time Lead time

      Optional Type: Number

      Provides the expected delivery time in days

      Example: 3

    • image_url Image URL

      Optional Format: protocol://domain/path

      Provides the full public URL to an image of the item

      Example: "https://www.mystorefront.com/images/product/77-1206.jpg"

    • is_catchweight Catch weight indicator

      Optional Accepted values: 0, 1

      Indicates whether the item is priced according to its exact shipping weight, which may differ from the expected weight

      Example: 0 = not according to weight, 1 = according to weight

 

Response payload (from TradeCentric)

Once our platform receives the return cart payload, we don’t validate the data yet. If the payload is in our standard format, we'll always return a HTTP 200 OK status and a response body with the redirect URL.

Note: We recommend that you configure a browser redirect from your eCommerce platform to the redirect URL so that we can return the user to their eProcurement system. 

The code block below shows an example response payload in our standard JSON format:

JSON
HTTP response
Return cart response
{
  "redirect_url": "https://connect.tradecentric.com/gateway/link/return/id/ABCD1234efg567?redirect=1"
}

 

Response field details

The response only includes a redirect_url field, which you can use to redirect the user.

Response field breakdown
  • redirect_url
    Redirect URL

    Required Type: String Format: protocol://domain/path

    Provides the full TradeCentric redirect URL, including the unique session identifier, from the session request payload that we sent

    Example: "https://connect.tradecentric.com/gateway/link/return/id/ABCD1234efg567?redirect=1"

Was this article helpful?
0 out of 0 found this helpful
Return to top
© 2026 TradeCentric. All rights reserved.
Confidential and proprietary. For use by TradeCentric and organizations under NDA only. Not for public distribution.

Related articles