# cart.addons

> Requests add-ons to be shown based on the shopper's cart contents.

Source: https://help.boltapp.com/api-reference/merchant-callback-reference/cart/cart-addons

`POST /universal_api`

## OpenAPI definition

This endpoint as it appears in the OpenAPI document, with every schema it references included.

```json
{
  "openapi": "3.2.0",
  "info": {
    "version": "1.0.0",
    "title": "Merchant Callback API Reference",
    "description": "## About\nThe Merchant Callback API is a general endpoint on your eCommerce server that Bolt calls to receive information necessary for operating the checkout process.\n\n**Note**: You must also reference the [Bolt API](/api-bolt) when building a custom cart integration.\n\n### URL Options\nYou can set the URL(s) for your Merchant Callback API in the [Bolt Merchant dashboard](https://merchant.boltapp.com).\n- **v1**: v1 endpoints are individualized and described in the subsections below with unique URLs (e.g., `/order_shipping_and_tax`)\n- **Universal**: The \"Universal API\" is one endpoint (instead of many) that handles all events described in this spec; the methods and payloads are identical, however you only need to use one URL.\n\nNeed more information? See our [Developer reference articles](/developers/references/) for **environment details**, **error codes**, and more.\n"
  },
  "servers": [
    {
      "url": "https://merchant-url.com/api"
    }
  ],
  "paths": {
    "/universal_api": {
      "post": {
        "summary": "cart.addons",
        "operationId": "cart.addons",
        "description": "Requests add-ons to be shown based on the shopper's cart contents.\n",
        "security": [
          {
            "ApiKeyAuth": [
              "X-API-Key"
            ]
          }
        ],
        "tags": [
          "Cart"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/bolt_hmac_param"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/cart_addons"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/cart_addons"
          },
          "422": {
            "$ref": "#/components/responses/cart_addons_error"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "bolt_hmac_param": {
        "in": "header",
        "name": "X-Bolt-Hmac-Sha256",
        "schema": {
          "type": "string"
        },
        "description": "Bolt sends a signed HMAC for hook verification"
      }
    },
    "requestBodies": {
      "cart_addons": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "event": {
                  "type": "string",
                  "enum": [
                    "cart.addons"
                  ]
                },
                "data": {
                  "type": "object",
                  "description": "This is a generic wrapper for the merchant's data. Open to see properties.",
                  "properties": {
                    "cart": {
                      "$ref": "#/components/schemas/addons_cart"
                    },
                    "addons_limit": {
                      "$ref": "#/components/schemas/addons_limit"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "addons_cart": {
        "type": "object",
        "required": [
          "items",
          "currency",
          "total_amount",
          "display_id",
          "order_reference"
        ],
        "properties": {
          "items": {
            "$ref": "#/components/schemas/addons_cart_items"
          },
          "currency": {
            "$ref": "#/components/schemas/currency_iso"
          },
          "total_amount": {
            "$ref": "#/components/schemas/cart_total_amount"
          },
          "display_id": {
            "$ref": "#/components/schemas/display_id"
          },
          "order_reference": {
            "$ref": "#/components/schemas/order_reference"
          },
          "discounts": {
            "$ref": "#/components/schemas/addons_cart_discounts"
          }
        }
      },
      "addons_cart_items": {
        "type": "array",
        "description": "A list of cart items.",
        "items": {
          "$ref": "#/components/schemas/cart_item"
        }
      },
      "cart_item": {
        "type": "object",
        "required": [
          "reference",
          "name",
          "total_amount",
          "unit_price",
          "quantity",
          "sku"
        ],
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/reference"
          },
          "name": {
            "$ref": "#/components/schemas/name_item"
          },
          "unit_price": {
            "$ref": "#/components/schemas/item_price"
          },
          "total_amount": {
            "$ref": "#/components/schemas/item_amount"
          },
          "quantity": {
            "$ref": "#/components/schemas/quantity"
          },
          "sku": {
            "$ref": "#/components/schemas/sku"
          },
          "description": {
            "$ref": "#/components/schemas/item_description"
          }
        }
      },
      "reference": {
        "type": "string",
        "description": "Reference for the object.",
        "examples": [
          "1123"
        ]
      },
      "name_item": {
        "type": "string",
        "description": "The name of an item.",
        "examples": [
          "Blue Hat"
        ]
      },
      "item_price": {
        "type": "integer",
        "format": "int64",
        "description": "Price per unit in cents.",
        "examples": [
          5000
        ]
      },
      "item_amount": {
        "type": "integer",
        "format": "int64",
        "description": "Item total amount.",
        "examples": [
          15000
        ]
      },
      "quantity": {
        "type": "integer",
        "description": "The quantity of this item.",
        "examples": [
          3
        ]
      },
      "sku": {
        "type": "string",
        "description": "The SKU identifier for this item or service.",
        "examples": [
          "SKU-11021"
        ]
      },
      "item_description": {
        "type": "string",
        "description": "A description for the item added to the cart/order.",
        "examples": [
          " Large blue satin hat with initials embroidered."
        ]
      },
      "currency_iso": {
        "type": "string",
        "description": "The 3-digit ISO code for the currency. **Nullable** for Transactions Details.",
        "examples": [
          "USD"
        ]
      },
      "cart_total_amount": {
        "type": "integer",
        "format": "int64",
        "description": "Cart total amount.",
        "examples": [
          13000
        ]
      },
      "display_id": {
        "type": "string",
        "description": "The displayed ID.",
        "examples": [
          "ID-12345"
        ]
      },
      "order_reference": {
        "type": "string",
        "description": "The order reference.",
        "examples": [
          "order-12345"
        ]
      },
      "addons_cart_discounts": {
        "type": "array",
        "description": "A list of cart discounts. (optional)",
        "items": {
          "$ref": "#/components/schemas/discount"
        }
      },
      "discount": {
        "type": "object",
        "required": [
          "amount",
          "code",
          "reference"
        ],
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/discount_amount"
          },
          "code": {
            "$ref": "#/components/schemas/discount_code"
          },
          "reference": {
            "$ref": "#/components/schemas/discount_reference"
          },
          "description": {
            "$ref": "#/components/schemas/discount_description"
          },
          "discount_category": {
            "$ref": "#/components/schemas/discount_category"
          },
          "type": {
            "$ref": "#/components/schemas/discount_type"
          }
        }
      },
      "discount_amount": {
        "type": "integer",
        "format": "int64",
        "description": "Discount amount.",
        "examples": [
          2000
        ]
      },
      "discount_code": {
        "type": "string",
        "description": "The discount code input by a shopper.",
        "examples": [
          "SUMMERFUN15"
        ]
      },
      "discount_reference": {
        "type": "string",
        "description": "The discount's reference.",
        "examples": [
          "discount-1234"
        ]
      },
      "discount_description": {
        "type": "string",
        "description": "The discount code's description.",
        "examples": [
          "Take 15% off of your order."
        ]
      },
      "discount_category": {
        "type": "string",
        "description": "The discount's category.",
        "enum": [
          "coupon",
          "gift_card",
          "managed_giftcard",
          "store_credit",
          "automatic_promotion",
          "membership_discount",
          "unknown"
        ],
        "examples": [
          "coupon"
        ]
      },
      "discount_type": {
        "type": "string",
        "enum": [
          "fixed_amount",
          "percentage",
          "shipping"
        ],
        "description": "The type of discount (e.g., percentage)",
        "examples": [
          "percentage"
        ]
      },
      "addons_limit": {
        "type": "integer",
        "format": "int64",
        "description": "The maximum number of add-ons for a product that should be returned. Any add-ons beyond the limit will be ignored.",
        "examples": [
          3
        ]
      },
      "cart_addons": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/addons"
        }
      },
      "addons": {
        "type": "object",
        "required": [
          "name",
          "description",
          "reference",
          "image_url",
          "amount",
          "currency"
        ],
        "properties": {
          "name": {
            "$ref": "#/components/schemas/name_item"
          },
          "description": {
            "$ref": "#/components/schemas/item_description"
          },
          "reference": {
            "$ref": "#/components/schemas/reference"
          },
          "image_url": {
            "$ref": "#/components/schemas/image_url"
          },
          "amount": {
            "$ref": "#/components/schemas/item_amount"
          },
          "currency": {
            "$ref": "#/components/schemas/currency_iso"
          },
          "product_page_url": {
            "$ref": "#/components/schemas/pdp_url"
          }
        }
      },
      "image_url": {
        "type": "string",
        "description": "The URL for the item's image.",
        "examples": [
          "https://boltswagstore.com/inventory/hats/red-hat.png"
        ]
      },
      "pdp_url": {
        "type": "string",
        "description": "The full product page url."
      },
      "error": {
        "type": "object",
        "properties": {
          "code": {
            "$ref": "#/components/schemas/code"
          },
          "data": {
            "$ref": "#/components/schemas/reasons"
          }
        }
      },
      "code": {
        "type": "integer",
        "format": "int64",
        "description": "This is an error code.",
        "examples": [
          2001005
        ]
      },
      "reasons": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/reason"
        }
      },
      "reason": {
        "type": "object",
        "description": "The reason for the error.",
        "properties": {
          "reason": {
            "type": "string",
            "examples": [
              "This product is out of stock."
            ]
          }
        }
      }
    },
    "responses": {
      "cart_addons": {
        "description": "Cart Addons Received Successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "event",
                "status",
                "data"
              ],
              "properties": {
                "event": {
                  "type": "string",
                  "enum": [
                    "cart.addons"
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "success"
                  ]
                },
                "data": {
                  "type": "object",
                  "description": "This is a generic wrapper for the merchant API’s request body.",
                  "properties": {
                    "addons": {
                      "$ref": "#/components/schemas/cart_addons"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "cart_addons_error": {
        "description": "Fetching Cart Addons Error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "event": {
                  "type": "string",
                  "enum": [
                    "cart.addons"
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "failure"
                  ]
                },
                "errors": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/error"
                  }
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Admins and Developers can obtain their Bolt API key from the Bolt Merchant Dashboard."
      }
    }
  }
}
```