Add Checkout Billing Address

POST

https://api.bigcommerce.com/stores/:store_hash/v3/checkouts/:checkoutId/billing-address

POST

/stores/:store_hash/v3/checkouts/:checkoutId/billing-address

curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/checkouts/checkoutId/billing-address \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "email": "string",
  "country_code": "string"
}'

{
  "data": {
    "id": "306d57d7-124e-4112-82cd-35e060c0d4d9",
    "cart": {
      "id": "306d57d7-124e-4112-82cd-35e060c0d4d9",
      "customer_id": 11,
      "email": "janedoe@example.com",
      "currency": {
        "code": "USD"
      },
      "base_amount": 31.95,
      "channel_id": 1,
      "discount_amount": 0,
      "cart_amount_inc_tax": 33.23,
      "cart_amount_ex_tax": 31.95,
      "coupons": [
        {
          "code": "SHOP20",
          "id": 1,
          "coupon_type": "percentage_discount",
          "discounted_amount": 0.9,
          "display_name": "20% Off"
        }
      ],
      "discounts": [
        {
          "id": "8edef915-8e8e-4ebd-bece-31fbb1191a7e",
          "discounted_amount": 0
        }
      ],
      "line_items": {
        "physical_items": [
          {
            "quantity": 1,
            "id": "8edef915-8e8e-4ebd-bece-31fbb1191a7e",
            "variant_id": 359,
            "product_id": 188,
            "sku": "DUST1",
            "name": "Hello",
            "url": "https://{store_hash}/all/dustpan-brush/",
            "is_taxable": true,
            "image_url": "https://cdn11.bigcommerce.com/s-{store_hash}/products/188/images/460/dustpan1_1024x1024_1024x1024__43447__69128.1534344539.330.500.jpg?c=2",
            "discounts": [],
            "discount_amount": 0,
            "coupon_amount": 0,
            "original_price": 35.95,
            "list_price": 31.95,
            "sale_price": 33.23,
            "extended_list_price": 31.95,
            "extended_sale_price": 33.23,
            "is_require_shipping": true,
            "parent_id": 123,
            "gift_wrapping": {},
            "coupons": []
          }
        ],
        "digital_items": [],
        "gift_certificates": [],
        "custom_items": []
      },
      "created_time": "2019-08-05T15:38:14+00:00",
      "updated_time": "2019-08-05T15:41:28+00:00"
    },
    "billing_address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "janedoe@example.com",
      "company": "BigCommerce",
      "address1": "123 Main Street",
      "address2": "Apt 1",
      "city": "Austin",
      "state_or_province": "",
      "state_or_province_code": "",
      "country_code": "",
      "postal_code": "",
      "phone": "12125685555",
      "custom_fields": [],
      "id": "5d484d668e5aa",
      "country": ""
    },
    "consignments": [
      {
        "id": "5d484e28d20a8",
        "address": {
          "email": "jane2@example.com",
          "country_code": "US",
          "first_name": "BigCommerce",
          "last_name": "Cart/Checkout",
          "company": "",
          "address1": "123 Main Street",
          "address2": "",
          "city": "Austin",
          "state_or_province": "Texas",
          "state_or_province_code": "TX",
          "postal_code": "78751",
          "phone": "688546",
          "country": "United States",
          "customFields": [
            {
              "field_id": "field_25",
              "field_value": "Great!"
            }
          ]
        },
        "available_shipping_options": [
          {
            "description": "Ship by Weight",
            "id": "006a58a98c9a844225552ee2a9c60ca8",
            "type": "shipping_byweight",
            "image_url": "",
            "cost": 8,
            "transit_time": "",
            "additional_description": ""
          },
          {
            "description": "Flat Rate",
            "id": "722d78b5120de60a725e41be9bb8d999",
            "type": "shipping_flatrate",
            "image_url": "",
            "cost": 12,
            "transit_time": "",
            "additional_description": ""
          },
          {
            "description": "UPS® (UPS Next Day Air®)",
            "id": "71090fa93c8985348892543c3f4887b6",
            "type": "shipping_upsready",
            "image_url": "",
            "cost": 43.9,
            "transit_time": "1 business day",
            "additional_description": ""
          }
        ],
        "coupon_discounts": [],
        "discounts": [],
        "shipping_cost_inc_tax": 0,
        "shipping_cost_ex_tax": 0,
        "handling_cost_inc_tax": 0,
        "handling_cost_ex_tax": 0,
        "line_item_ids": [
          "8edef915-8e8e-4ebd-bece-31fbb1191a7e"
        ]
      }
    ],
    "taxes": [
      {
        "name": "Tax",
        "amount": 1.28
      }
    ],
    "coupons": [
      {
        "code": "SHOP20",
        "id": 1,
        "coupon_type": "percentage_discount",
        "display_name": "20% Off",
        "discounted_amount": 0.9
      }
    ],
    "shipping_cost_total_inc_tax": 0,
    "shipping_cost_total_ex_tax": 0,
    "handling_cost_total_inc_tax": 0,
    "handling_cost_total_ex_tax": 0,
    "tax_total": 1.28,
    "subtotal_inc_tax": 33.23,
    "subtotal_ex_tax": 31.95,
    "grand_total": 33.23,
    "created_time": "2019-08-05T15:38:14+00:00",
    "updated_time": "2019-08-05T15:41:28+00:00",
    "customer_message": "",
    "version": 1
  },
  "meta": {}
}

Adds a billing address to an existing checkout.

Required Fields

email
country_code

To prevent lost updates due to concurrent requests overriding changes made by others, it is recommended to enable optimistic concurrency control by including the version field in the request payload. If the provided version does not match the version on the server, a conflict error will be returned, which the client can handle accordingly.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Checkouts	modify	`store_checkouts`
Checkouts	read-only	`store_checkouts_read_only`
Checkout Content	modify	`store_checkout_content`
Checkout Content	read-only	`store_checkout_content_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

Path parameters

checkoutIdstringRequired

ID of the checkout; the same as the cart ID.

store_hashstringRequired

Permanent ID of the BigCommerce store.

Request

This endpoint expects an object.

emailstringRequired

country_codestringRequired

first_namestringOptional

last_namestringOptional

companystringOptional

address1stringOptional

address2stringOptional

citystringOptional

state_or_provincestringOptional

Represents state or province.

state_or_province_codestringOptional

postal_codestringOptional

phonestringOptionalformat: "^\+?[1-9]\d{1,14}(x\d{1-5})?$"

custom_fieldslist of objectsOptional

You can retrieve custom fields from the Get Form Fields endpoint.

versionintegerOptional

The cart version that you expect to apply the updates. If the provided version doesn’t match the current cart version, you will receive a conflict error. This field is optional; if not provided, optimistic concurrency control will not apply.

Response

dataobjectOptional

metaobjectOptional

Response metadata.

Errors

409

Conflict Error