# cart.create

> This is only used for Product-Page Checkout to create a cart filled with items.

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

`POST /cart_create`

## 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": {
    "/cart_create": {
      "post": {
        "summary": "cart.create",
        "operationId": "cart.create",
        "description": "This is only used for Product-Page Checkout to create a cart filled with items.\n",
        "security": [
          {
            "ApiKeyAuth": [
              "X-API-Key"
            ]
          }
        ],
        "tags": [
          "Cart"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/bolt_hmac_param"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/cart_create"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/cart_create"
          },
          "422": {
            "$ref": "#/components/responses/cart_create_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_create": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "event": {
                  "type": "string",
                  "enum": [
                    "cart.create"
                  ]
                },
                "data": {
                  "type": "object",
                  "description": "This is a generic wrapper for the merchant's data. Open to see properties.",
                  "properties": {
                    "items": {
                      "$ref": "#/components/schemas/items"
                    },
                    "currency": {
                      "$ref": "#/components/schemas/currency_iso"
                    },
                    "metadata": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key1": {
                            "type": "string",
                            "examples": [
                              "value 1"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "items": {
        "type": "array",
        "description": "A list of items.",
        "items": {
          "$ref": "#/components/schemas/item"
        }
      },
      "item": {
        "type": "object",
        "description": "An item with properties.",
        "required": [
          "reference",
          "name",
          "total_amount",
          "unit_price",
          "quantity"
        ],
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/reference"
          },
          "name": {
            "$ref": "#/components/schemas/name_item"
          },
          "description": {
            "$ref": "#/components/schemas/item_description"
          },
          "options": {
            "$ref": "#/components/schemas/options"
          },
          "total_amount": {
            "$ref": "#/components/schemas/total_amount"
          },
          "unit_price": {
            "$ref": "#/components/schemas/unit_price"
          },
          "tax_amount": {
            "$ref": "#/components/schemas/amounts"
          },
          "quantity": {
            "$ref": "#/components/schemas/quantity"
          },
          "uom": {
            "type": "string",
            "examples": [
              "string"
            ]
          },
          "upc": {
            "type": "string",
            "examples": [
              "string"
            ]
          },
          "sku": {
            "$ref": "#/components/schemas/sku"
          },
          "isbn": {
            "$ref": "#/components/schemas/isbn"
          },
          "brand": {
            "$ref": "#/components/schemas/brand"
          },
          "manufacturer": {
            "$ref": "#/components/schemas/manufacturer"
          },
          "category": {
            "$ref": "#/components/schemas/category"
          },
          "collections": {
            "$ref": "#/components/schemas/collections"
          },
          "tags": {
            "$ref": "#/components/schemas/tag"
          },
          "color": {
            "$ref": "#/components/schemas/color"
          },
          "size": {
            "$ref": "#/components/schemas/size"
          },
          "weight": {
            "$ref": "#/components/schemas/total_weight"
          },
          "image_url": {
            "$ref": "#/components/schemas/image_url"
          },
          "details_url": {
            "type": "string",
            "description": "The URL for the item's details.",
            "examples": [
              "https://boltswagstore.com/inventory/hats/red-hat.png"
            ]
          },
          "type": {
            "$ref": "#/components/schemas/type"
          },
          "taxable": {
            "$ref": "#/components/schemas/taxable"
          },
          "properties": {
            "$ref": "#/components/schemas/item_properties"
          },
          "item_group": {
            "$ref": "#/components/schemas/item_group"
          },
          "shipment_type": {
            "$ref": "#/components/schemas/item_shipment_type"
          },
          "customizations": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "price",
                "attributes"
              ],
              "properties": {
                "name": {
                  "$ref": "#/components/schemas/customizations_name"
                },
                "price": {
                  "$ref": "#/components/schemas/amounts"
                },
                "attributes": {
                  "$ref": "#/components/schemas/metadata_component"
                }
              }
            }
          },
          "bolt_product_id": {
            "$ref": "#/components/schemas/bolt_product_id"
          },
          "gift_options": {
            "$ref": "#/components/schemas/gift_options"
          }
        }
      },
      "reference": {
        "type": "string",
        "description": "Reference for the object.",
        "examples": [
          "1123"
        ]
      },
      "name_item": {
        "type": "string",
        "description": "The name of an item.",
        "examples": [
          "Blue Hat"
        ]
      },
      "item_description": {
        "type": "string",
        "description": "A description for the item added to the cart/order.",
        "examples": [
          " Large blue satin hat with initials embroidered."
        ]
      },
      "options": {
        "type": "string",
        "examples": [
          "string option"
        ]
      },
      "total_amount": {
        "type": "integer",
        "description": "The total amount.",
        "examples": [
          9900
        ]
      },
      "unit_price": {
        "type": "integer",
        "description": "Price per unit in cents.",
        "examples": [
          500
        ]
      },
      "amounts": {
        "type": "object",
        "description": "The amount. **Nullable** for Transactions Details.",
        "required": [
          "amount",
          "currency",
          "currency_symbol"
        ],
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "currency": {
            "$ref": "#/components/schemas/currency_iso"
          },
          "currency_symbol": {
            "$ref": "#/components/schemas/currency_symbol"
          }
        }
      },
      "amount": {
        "type": "integer",
        "description": "The amount in cents. **Nullable** for Transactions Details.",
        "examples": [
          754
        ]
      },
      "currency_iso": {
        "type": "string",
        "description": "The 3-digit ISO code for the currency. **Nullable** for Transactions Details.",
        "examples": [
          "USD"
        ]
      },
      "currency_symbol": {
        "type": "string",
        "description": "The currency symbol used for the amount. **Nullable** for Transactions Details.",
        "examples": [
          "$"
        ]
      },
      "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"
        ]
      },
      "isbn": {
        "type": "string",
        "description": "A 13-digit identifier for a book item.",
        "examples": [
          "12-345-678-90123"
        ]
      },
      "brand": {
        "type": "string",
        "description": "The name of a brand.",
        "examples": [
          "Bolt Swagstore"
        ]
      },
      "manufacturer": {
        "type": "string",
        "description": "The name of a manufacturer.",
        "examples": [
          "Bolt Factory"
        ]
      },
      "category": {
        "type": "string",
        "description": "A category.",
        "examples": [
          "hats"
        ]
      },
      "collections": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/collection"
        }
      },
      "collection": {
        "type": "string",
        "examples": [
          "summer"
        ]
      },
      "tag": {
        "type": "string",
        "description": "A tag",
        "examples": [
          "red"
        ]
      },
      "color": {
        "type": "string",
        "description": "The color.",
        "examples": [
          "Red"
        ]
      },
      "size": {
        "type": "string",
        "description": "The size.",
        "examples": [
          "XXL"
        ]
      },
      "total_weight": {
        "type": "object",
        "properties": {
          "weight": {
            "$ref": "#/components/schemas/weight"
          },
          "unit": {
            "$ref": "#/components/schemas/weight_unit"
          }
        }
      },
      "weight": {
        "type": "integer",
        "description": "The weight of an item.",
        "examples": [
          22
        ]
      },
      "weight_unit": {
        "type": "string",
        "description": "The unit of measurement for an item's weight.",
        "examples": [
          "kg"
        ]
      },
      "image_url": {
        "type": "string",
        "description": "The URL for the item's image.",
        "examples": [
          "https://boltswagstore.com/inventory/hats/red-hat.png"
        ]
      },
      "type": {
        "type": "string",
        "enum": [
          "bundled",
          "digital",
          "physical",
          "unknown"
        ],
        "description": "Determines if item is a physical, digital, or bundled good, or if the good type is unknown.",
        "examples": [
          "physical"
        ]
      },
      "taxable": {
        "type": "boolean",
        "description": "Determines if item is taxable.",
        "examples": [
          true
        ]
      },
      "item_properties": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/item_property"
        }
      },
      "item_property": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "examples": [
              "a-name"
            ]
          },
          "value": {
            "type": "string",
            "examples": [
              "a-value"
            ]
          }
        }
      },
      "item_group": {
        "type": "string",
        "description": "Enables grouping in the checkout UI.",
        "examples": [
          "Ships Immediately"
        ]
      },
      "item_shipment_type": {
        "type": "string",
        "description": "The shipment type selected by the shopper.",
        "enum": [
          "unknown",
          "door delivery",
          "in_store_pickup",
          "ship_to_store"
        ]
      },
      "customizations_name": {
        "type": "string",
        "description": "The name of the customization.",
        "examples": [
          "Bedazzled"
        ]
      },
      "metadata_component": {
        "type": "object",
        "properties": {
          "key1": {
            "type": "string",
            "examples": [
              "value1"
            ]
          },
          "key2": {
            "type": "string",
            "examples": [
              "value2"
            ]
          }
        }
      },
      "bolt_product_id": {
        "type": "string",
        "description": "Unique ID generated for a product via the products endpoint.",
        "examples": [
          "e2bb0e7e-5625-536f-8ad7-25a26537ee28"
        ]
      },
      "gift_options": {
        "type": "object",
        "description": "Contains the gift option settings for wrapping and custom messages.",
        "required": [
          "wrap",
          "merchant_product_id"
        ],
        "properties": {
          "wrap": {
            "$ref": "#/components/schemas/gift_options_wrap"
          },
          "message": {
            "$ref": "#/components/schemas/gift_options_message"
          },
          "cost": {
            "$ref": "#/components/schemas/gift_options_cost"
          },
          "merchant_product_id": {
            "$ref": "#/components/schemas/merchant_product_id"
          }
        }
      },
      "gift_options_wrap": {
        "type": "boolean",
        "description": "Defines whether gift wrapping was requested.",
        "examples": [
          false
        ]
      },
      "gift_options_message": {
        "type": "string",
        "description": "Includes the gift message written by the shopper.",
        "examples": [
          "Happy Anniversary, Smoochy Poo!"
        ]
      },
      "gift_options_cost": {
        "type": "integer",
        "description": "Defines the price of gift wrapping this item. Required if `wrap` = `true`.\n",
        "examples": [
          785
        ]
      },
      "merchant_product_id": {
        "type": "string",
        "description": "The merchant's unique ID for the product.",
        "examples": [
          "881"
        ]
      },
      "order_create_cart": {
        "type": "object",
        "required": [
          "currency"
        ],
        "properties": {
          "total_amount": {
            "$ref": "#/components/schemas/total_amount"
          },
          "items": {
            "$ref": "#/components/schemas/items"
          },
          "discounts": {
            "$ref": "#/components/schemas/discounts"
          },
          "order_reference": {
            "$ref": "#/components/schemas/order_reference"
          },
          "display_id": {
            "$ref": "#/components/schemas/display_id"
          },
          "cart_url": {
            "$ref": "#/components/schemas/cart_url"
          },
          "currency": {
            "$ref": "#/components/schemas/currency_iso"
          },
          "metadata": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key1": {
                  "type": "string",
                  "examples": [
                    "value 1"
                  ]
                }
              }
            }
          }
        }
      },
      "discounts": {
        "type": "array",
        "description": "A list of discounts.",
        "items": {
          "type": "object",
          "properties": {
            "amount": {
              "$ref": "#/components/schemas/amounts"
            },
            "code": {
              "$ref": "#/components/schemas/discount_code"
            },
            "reference": {
              "$ref": "#/components/schemas/discount_code"
            },
            "description": {
              "$ref": "#/components/schemas/discount_description"
            },
            "details_url": {
              "$ref": "#/components/schemas/discount_uri"
            },
            "free_shipping": {
              "$ref": "#/components/schemas/discount_free_shipping"
            },
            "discount_category": {
              "$ref": "#/components/schemas/discount_category"
            }
          }
        }
      },
      "discount_code": {
        "type": "string",
        "description": "The discount code input by a shopper.",
        "examples": [
          "SUMMERFUN15"
        ]
      },
      "discount_description": {
        "type": "string",
        "description": "The discount code's description.",
        "examples": [
          "Take 15% off of your order."
        ]
      },
      "discount_uri": {
        "type": "string",
        "description": "The discount's URI.",
        "examples": [
          "https://boltswagstore.com/discounts/#12345"
        ]
      },
      "discount_free_shipping": {
        "type": "object",
        "description": "Contains free shipping settings and limitations.",
        "properties": {
          "is_free_shipping": {
            "$ref": "#/components/schemas/is_free_shipping"
          },
          "maximum_cost_allowed": {
            "$ref": "#/components/schemas/maximum_cost_allowed"
          }
        }
      },
      "is_free_shipping": {
        "type": "boolean",
        "examples": [
          false
        ]
      },
      "maximum_cost_allowed": {
        "type": "integer",
        "examples": [
          100
        ]
      },
      "discount_category": {
        "type": "string",
        "description": "The discount's category.",
        "enum": [
          "coupon",
          "gift_card",
          "managed_giftcard",
          "store_credit",
          "automatic_promotion",
          "membership_discount",
          "unknown"
        ],
        "examples": [
          "coupon"
        ]
      },
      "order_reference": {
        "type": "string",
        "description": "The order reference.",
        "examples": [
          "order-12345"
        ]
      },
      "display_id": {
        "type": "string",
        "description": "The displayed ID.",
        "examples": [
          "ID-12345"
        ]
      },
      "cart_url": {
        "type": "string",
        "description": "The URL for the cart.",
        "examples": [
          "https://boltswagstore.com/orders/123456765432"
        ]
      },
      "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_create": {
        "description": "Cart Created Successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "event",
                "status",
                "data"
              ],
              "properties": {
                "event": {
                  "type": "string",
                  "enum": [
                    "cart.create"
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "success"
                  ]
                },
                "data": {
                  "type": "object",
                  "description": "This is a generic wrapper for the merchant API’s request body.",
                  "properties": {
                    "cart": {
                      "$ref": "#/components/schemas/order_create_cart"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "cart_create_error": {
        "description": "Cart Create Error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "event": {
                  "type": "string",
                  "enum": [
                    "cart.create"
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "failure"
                  ]
                },
                "error": {
                  "$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."
      }
    }
  }
}
```