POST
/
v1
/
merchant
/
orders
Create Order Token
curl --request POST \
  --url https://api.bolt.com/v1/merchant/orders \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "cart": {
    "total_amount": 900,
    "currency": "USD",
    "order_reference": "order_100",
    "add_ons": [
      {
        "name": "<string>",
        "price": 123,
        "productId": "<string>",
        "description": "<string>",
        "imageUrl": "<string>",
        "productPageUrl": "<string>"
      }
    ],
    "discounts": [
      {
        "amount": 100,
        "code": "SUMMER10DISCOUNT",
        "description": "10% off our summer collection",
        "details_url": "https://boltswagstore.com/SUMMERSALE",
        "reference": "DISC-1234",
        "type": "percentage"
      }
    ],
    "fees": [
      {
        "reference": "ItemFee",
        "name": "Item Fee",
        "unit_price": 123,
        "unit_tax_amount": 123,
        "quantity": 123,
        "description": "Item Fee"
      }
    ],
    "fulfillments": [
      {
        "cart_items": [
          {
            "name": "Bolt Swag Bag",
            "quantity": 1,
            "reference": "item_100",
            "total_amount": 1000,
            "unit_price": 1000,
            "brand": "Bolt",
            "category": "bags",
            "collections": [
              "summer"
            ],
            "color": "Bolt Blue",
            "customizations": [
              {
                "attributes": {
                  "key1": "value1",
                  "key2": "value2"
                },
                "name": "<string>",
                "price": 754
              }
            ],
            "description": "Large tote with Bolt logo.",
            "details_url": "https://boltswagstore.com/products/123456",
            "external_inputs": {
              "shopify_line_item_reference": 123,
              "shopify_product_reference": 123,
              "shopify_product_variant_reference": 123
            },
            "gift_option": {
              "cost": 770,
              "merchant_product_id": "881",
              "message": "Happy Anniversary, Smoochy Poo!",
              "wrap": false
            },
            "image_url": "https://boltswagstore.com/products/123456/images/1.png",
            "isbn": "9780091347314",
            "item_group": "<string>",
            "manufacturer": "Bolt Textiles USA",
            "merchant_product_id": "881",
            "merchant_variant_id": "888",
            "msrp": 123,
            "options": "Special Edition",
            "properties": [
              {
                "color": "<string>",
                "display": true,
                "name": "<string>",
                "name_id": 123,
                "value": "<string>",
                "value_id": 123
              }
            ],
            "shipment": {
              "carrier": "FedEx",
              "cost": 770,
              "discounted_by_membership": false,
              "estimated_delivery_date": "08-30-2022",
              "expedited": false,
              "package_depth": 90,
              "package_dimension_unit": "cm",
              "package_height": 103,
              "package_type": "A big package.",
              "package_weight_unit": "kg",
              "package_width": 222,
              "service": "Option 1",
              "shipping_address_id": "address1",
              "shipping_method": "unknown",
              "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
              "tax_amount": 230,
              "tax_code": "tax-12345",
              "total_weight": 55,
              "total_weight_unit": "kg",
              "type": "door_delivery"
            },
            "size": "Large",
            "sku": "BOLT-SKU_100",
            "source": "<string>",
            "seller_id": "seller-1234",
            "tags": "tote, blue, linen, eco-friendly",
            "tax_amount": 0,
            "tax_code": "<string>",
            "taxable": true,
            "uom": "inches",
            "upc": "0825764603119",
            "weight": 10,
            "weight_unit": "pounds"
          }
        ],
        "cart_shipment": {
          "carrier": "FedEx",
          "cost": 770,
          "discounted_by_membership": false,
          "estimated_delivery_date": "08-30-2022",
          "expedited": false,
          "package_depth": 90,
          "package_dimension_unit": "cm",
          "package_height": 103,
          "package_type": "A big package.",
          "package_weight_unit": "kg",
          "package_width": 222,
          "service": "Option 1",
          "shipping_address_id": "address1",
          "shipping_method": "unknown",
          "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
          "tax_amount": 230,
          "tax_code": "tax-12345",
          "total_weight": 55,
          "total_weight_unit": "kg",
          "type": "door_delivery"
        },
        "digital_delivery": {
          "email": "<string>",
          "phone": "<string>"
        },
        "in_store_cart_shipment": {
          "cart_shipment": {
            "carrier": "FedEx",
            "cost": 770,
            "discounted_by_membership": false,
            "estimated_delivery_date": "08-30-2022",
            "expedited": false,
            "package_depth": 90,
            "package_dimension_unit": "cm",
            "package_height": 103,
            "package_type": "A big package.",
            "package_weight_unit": "kg",
            "package_width": 222,
            "service": "Option 1",
            "shipping_address_id": "address1",
            "shipping_method": "unknown",
            "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
            "tax_amount": 230,
            "tax_code": "tax-12345",
            "total_weight": 55,
            "total_weight_unit": "kg",
            "type": "door_delivery"
          },
          "description": "Pick up in-store at 123 Main St.",
          "distance": 3,
          "distance_unit": "mile",
          "pickup_window_close": 123,
          "pickup_window_open": 123,
          "store_name": "Bolt Collective"
        }
      }
    ],
    "in_store_cart_shipments": [
      {
        "cart_shipment": {
          "carrier": "FedEx",
          "cost": 770,
          "discounted_by_membership": false,
          "estimated_delivery_date": "08-30-2022",
          "expedited": false,
          "package_depth": 90,
          "package_dimension_unit": "cm",
          "package_height": 103,
          "package_type": "A big package.",
          "package_weight_unit": "kg",
          "package_width": 222,
          "service": "Option 1",
          "shipping_address_id": "address1",
          "shipping_method": "unknown",
          "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
          "tax_amount": 230,
          "tax_code": "tax-12345",
          "total_weight": 55,
          "total_weight_unit": "kg",
          "type": "door_delivery"
        },
        "description": "Pick up in-store at 123 Main St.",
        "distance": 3,
        "distance_unit": "mile",
        "pickup_window_close": 123,
        "pickup_window_open": 123,
        "store_name": "Bolt Collective"
      }
    ],
    "items": [
      {
        "name": "Bolt Swag Bag",
        "quantity": 1,
        "reference": "item_100",
        "total_amount": 1000,
        "unit_price": 1000,
        "brand": "Bolt",
        "category": "bags",
        "collections": [
          "summer"
        ],
        "color": "Bolt Blue",
        "customizations": [
          {
            "attributes": {
              "key1": "value1",
              "key2": "value2"
            },
            "name": "<string>",
            "price": 754
          }
        ],
        "description": "Large tote with Bolt logo.",
        "details_url": "https://boltswagstore.com/products/123456",
        "external_inputs": {
          "shopify_line_item_reference": 123,
          "shopify_product_reference": 123,
          "shopify_product_variant_reference": 123
        },
        "gift_option": {
          "cost": 770,
          "merchant_product_id": "881",
          "message": "Happy Anniversary, Smoochy Poo!",
          "wrap": false
        },
        "image_url": "https://boltswagstore.com/products/123456/images/1.png",
        "isbn": "9780091347314",
        "item_group": "<string>",
        "manufacturer": "Bolt Textiles USA",
        "merchant_product_id": "881",
        "merchant_variant_id": "888",
        "msrp": 123,
        "options": "Special Edition",
        "properties": [
          {
            "color": "<string>",
            "display": true,
            "name": "<string>",
            "name_id": 123,
            "value": "<string>",
            "value_id": 123
          }
        ],
        "shipment": {
          "carrier": "FedEx",
          "cost": 770,
          "discounted_by_membership": false,
          "estimated_delivery_date": "08-30-2022",
          "expedited": false,
          "package_depth": 90,
          "package_dimension_unit": "cm",
          "package_height": 103,
          "package_type": "A big package.",
          "package_weight_unit": "kg",
          "package_width": 222,
          "service": "Option 1",
          "shipping_address_id": "address1",
          "shipping_method": "unknown",
          "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
          "tax_amount": 230,
          "tax_code": "tax-12345",
          "total_weight": 55,
          "total_weight_unit": "kg",
          "type": "door_delivery"
        },
        "size": "Large",
        "sku": "BOLT-SKU_100",
        "source": "<string>",
        "seller_id": "seller-1234",
        "tags": "tote, blue, linen, eco-friendly",
        "tax_amount": 0,
        "tax_code": "<string>",
        "taxable": true,
        "uom": "inches",
        "upc": "0825764603119",
        "weight": 10,
        "weight_unit": "pounds"
      }
    ],
    "loyalty_rewards": [
      {
        "amount": 123,
        "coupon_code": "<string>",
        "description": "$5 off (100 Points)",
        "details": "{\"id\": 123456, \"icon\": \"fa-dollar\", \"name\": \"$15.00 Off\", \"type\": \"Coupon\", \"amount\": 100, \"duration\": \"single_use\", \"cost_text\": \"150 Points\",  \"description\": \"Get $15 off your next purchase for 150 points\", \"discount_type\": \"fixed_amount\", \"unrendered_name\": \"$15.00 Off\",  \"discount_percentage\": null, \"discount_rate_cents\": null, \"discount_value_cents\": null, \"discount_amount_cents\": 1500,  \"unrendered_description\": \"Get $15 off your next purchase for 150 points\", \"applies_to_product_type\": \"ALL\"}",
        "points": 123,
        "source": "<string>",
        "type": "<string>"
      }
    ],
    "shipments": [
      {
        "carrier": "FedEx",
        "cost": 770,
        "discounted_by_membership": false,
        "estimated_delivery_date": "08-30-2022",
        "expedited": false,
        "package_depth": 90,
        "package_dimension_unit": "cm",
        "package_height": 103,
        "package_type": "A big package.",
        "package_weight_unit": "kg",
        "package_width": 222,
        "service": "Option 1",
        "shipping_address_id": "address1",
        "shipping_method": "unknown",
        "signature": "a1B2s3dC4f5g5D6hj6E7k8F9l0",
        "tax_amount": 230,
        "tax_code": "tax-12345",
        "total_weight": 55,
        "total_weight_unit": "kg",
        "type": "door_delivery"
      }
    ],
    "tax_amount": 123,
    "cart_url": "https://boltswagstore.com/orders/123456765432",
    "display_id": "displayid_100",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "order_description": "Order #1234567890"
  },
  "create_cart_on_merchant_backend": false,
  "metadata": {
    "encrypted_user_id": "ID12345678"
  },
  "user_note": "Happy Birthday to my best friend in the whole world. Enjoy!",
  "seller_splits": [
    {
      "seller_id": "seller-1234",
      "amounts": {
        "merchant_subtotal": 5000,
        "discount_total": 500,
        "shipping_total": 1000,
        "tax_total": 400,
        "gross_total": 5900
      },
      "marketplace_commission_fee": {
        "bps": 250,
        "flat_cents": 100,
        "metadata": {
          "plan_type": "pro",
          "tier": "premium"
        }
      }
    }
  ]
}
'
{
  "cart": {
    "billing_address": {
      "company": "Bolt",
      "country": "United States",
      "country_code": "US",
      "door_code": "123456",
      "email_address": "alan.watts@example.com",
      "first_name": "Alan",
      "id": "<string>",
      "last_name": "Watts",
      "locality": "Brooklyn",
      "name": "Alan Watts",
      "phone_number": "+12125550199",
      "postal_code": "10044",
      "priority": "primary",
      "region": "NY",
      "region_code": "NY",
      "street_address1": "888 main street",
      "street_address2": "apt 3021",
      "street_address3": "c/o Alicia Watts",
      "street_address4": "Bridge Street Apartment Building B"
    },
    "cart_url": "https://boltswagstore.com/orders/123456765432",
    "currency": {
      "currency": "USD",
      "currency_symbol": "$"
    },
    "discount_amount": {
      "amount": 754,
      "currency": "USD",
      "currency_symbol": "$"
    },
    "discounts": [
      {
        "amount": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        },
        "code": "SUMMER10",
        "description": "10% off our summer collection",
        "details_url": "https://boltswagstore.com/SUMMERSALE",
        "free_shipping": {
          "is_free_shipping": true,
          "maximum_cost_allowed": 123
        },
        "reference": "DISC-1234"
      }
    ],
    "display_id": "displayid_100",
    "fee_amount": {
      "amount": 754,
      "currency": "USD",
      "currency_symbol": "$"
    },
    "fees": [
      {
        "reference": "ItemFee",
        "name": "Item Fee",
        "description": "Item Fee",
        "unit_price": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        },
        "unit_tax_amount": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        },
        "quantity": 123
      }
    ],
    "items": [
      {
        "bolt_product_id": "<string>",
        "brand": "<string>",
        "category": "bags",
        "collections": [
          "summer"
        ],
        "color": "Bolt Blue",
        "customizations": [
          {
            "attributes": {
              "key1": "value1",
              "key2": "value2"
            },
            "name": "<string>",
            "price": 754
          }
        ],
        "description": "<string>",
        "details_url": "https://boltswagstore.com/products/123456",
        "gift_option": {
          "hide_gift_message": false,
          "hide_gift_wrap": false
        },
        "hide": true,
        "image_url": "https://boltswagstore.com/products/123456/images/1.png",
        "isbn": 9780091347314,
        "item_group": "<string>",
        "manufacturer": "Bolt Textiles USA",
        "merchant_product_id": "<string>",
        "merchant_variant_id": "<string>",
        "msrp": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        },
        "name": "<string>",
        "options": "<string>",
        "properties": [
          {
            "color": "<string>",
            "display": true,
            "name": "<string>",
            "value": "<string>"
          }
        ],
        "quantity": 1,
        "reference": "<string>",
        "shipment_id": "<string>",
        "shopify_line_item_reference": 123,
        "shopify_product_reference": 123,
        "shopify_product_variant_reference": 123,
        "size": "Large",
        "sku": "BOLT-SKU_100",
        "subscription": {
          "frequency": {
            "unit": "month",
            "value": 2
          }
        },
        "tags": "tote, blue, linen, eco-friendly",
        "tax_amount": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        },
        "taxable": true,
        "total_amount": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        },
        "unit_price": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        },
        "uom": "inches",
        "upc": "0825764603119",
        "weight": {
          "unit": "<string>",
          "weight": 123
        }
      }
    ],
    "merchant_order_url": "<string>",
    "order_description": "Order #1234567890",
    "order_reference": "order_100",
    "shipments": [
      {
        "carrier": "USPS",
        "cost": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        },
        "default": true,
        "description": [
          {
            "content": "<string>",
            "is_html": true
          }
        ],
        "description_tooltips": [
          {
            "html_content": "<string>",
            "target": 123
          }
        ],
        "estimated_delivery_date": "2022-04-10 16:12:38.386000+00:00",
        "expedited": true,
        "gift_options": {
          "hide_gift_message": false,
          "hide_gift_wrap": false
        },
        "id": "<string>",
        "package_dimension": {
          "depth": 123,
          "height": 123,
          "unit": "<string>",
          "width": 123
        },
        "package_type": "<string>",
        "package_weight": {
          "unit": "<string>",
          "weight": 123
        },
        "reference": "<string>",
        "service": "<string>",
        "shipping_address": {
          "company": "Bolt",
          "country": "United States",
          "country_code": "US",
          "door_code": "123456",
          "email_address": "alan.watts@example.com",
          "first_name": "Alan",
          "id": "<string>",
          "last_name": "Watts",
          "locality": "Brooklyn",
          "name": "Alan Watts",
          "phone_number": "+12125550199",
          "postal_code": "10044",
          "priority": "primary",
          "region": "NY",
          "region_code": "NY",
          "street_address1": "888 main street",
          "street_address2": "apt 3021",
          "street_address3": "c/o Alicia Watts",
          "street_address4": "Bridge Street Apartment Building B"
        },
        "shipping_method": "<string>",
        "signature": "<string>",
        "tax_amount": {
          "amount": 754,
          "currency": "USD",
          "currency_symbol": "$"
        },
        "total_weight": {
          "unit": "<string>",
          "weight": 123
        },
        "type": "<string>"
      }
    ],
    "shipping_amount": {
      "amount": 754,
      "currency": "USD",
      "currency_symbol": "$"
    },
    "subtotal_amount": {
      "amount": 754,
      "currency": "USD",
      "currency_symbol": "$"
    },
    "tax_amount": {
      "amount": 754,
      "currency": "USD",
      "currency_symbol": "$"
    },
    "total_amount": {
      "amount": 754,
      "currency": "USD",
      "currency_symbol": "$"
    },
    "transaction_reference": "6CEA-ZME1-DACE"
  },
  "dynamic_content": {
    "custom_fields": [
      {
        "dynamic": true,
        "external_id": "<string>",
        "field_setup": "<string>",
        "helper_text": "<string>",
        "label": "<string>",
        "position": 123,
        "public_id": "<string>",
        "required": true,
        "subscribeToNewsletter": true
      }
    ],
    "eligible_payment_methods": [
      {
        "eligible": true
      }
    ],
    "gift_option_view": {
      "hide_gift_message": true,
      "hide_gift_wrap": true
    },
    "hide_apm": [],
    "order_notice": "<string>",
    "payment_notice": "<string>",
    "shipping_info_notice": "<string>",
    "shipping_notice": "<string>"
  },
  "external_data": {
    "steam_id": "<string>"
  },
  "token": "<string>",
  "user_note": "<string>"
}

Authorizations

​
X-API-Key
string
header
required

Admins and Developers can obtain their Bolt API key from the Bolt Merchant Dashboard.

Body

application/json

Generate Order Token

​
cart
object
required

The cart_create object is a composite of the base_cart object and additional order details.

​
channel
enum<string>
required

Used to determine the channel from which the order was created.

Available options:
browser,
mobile_app
​
create_cart_on_merchant_backend
boolean | null

Used to determine whether the order is created on your backend platform. This should almost always be false.

Example:

false

​
metadata
object
​
user_note
string

Optionally used by shoppers to make extra requests or provide details for gift messages.

Maximum string length: 1024
Example:

"Happy Birthday to my best friend in the whole world. Enjoy!"

​
seller_splits
object[] | null

Array of seller splits for marketplace orders. This enables marketplaces to dynamically configure commission fees and payment splits per seller. Each split contains seller identification, scoped line items and shipments, and declarative amount breakdowns.

Response

Token Generation Successful

​
cart
object

This is the cart object returned in a successful response.

​
dynamic_content
object
​
external_data
object
​
token
string
​
user_note
string

Used by shoppers to make extra requests or provide details for gift messages.