Thanks for being patient while we implement your feedback to improve the developer experience.

Add Checkout Billing Address

POST /checkouts/{checkoutId}/billing-address

Request

Adds a billing address to an existing Checkout.

Required Fields

  • country_code

Note

  • The email property is only required if the customer is a guest shopper. Otherwise, it is set automatically.
  • Sending email property as a payload in POST request triggers the abandoned cart notification process.
  • Substitute your storefront domain for yourstore.example.com.
  • The Send a Test Request feature is not currently supported for this endpoint.

Parameters

  • store_domain in path - string
  • checkoutId in path - string - required

Body

object | application/json

  • firstName    string

  • lastName    string

  • email    string

  • company    string

  • address1    string

  • address2    string

  • city    string

  • stateOrProvince    string

    Represents state or province.

  • stateOrProvinceCode    string

  • countryCode    string
    required

    ISO 3166-1 alpha-2 country code. (See: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

  • postalCode    string

  • phone    string

  • customFields    array[object]

example

{
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "company": "string",
  "address1": "string",
  "address2": "string",
  "city": "string",
  "stateOrProvince": "string",
  "stateOrProvinceCode": "string",
  "countryCode": "string",
  "postalCode": "string",
  "phone": "string",
  "customFields": [
    {
      "fieldId": "string",
      "fieldValue": "string"
    }
  ]
}

Response

Body

object | application/json

  • id    string

  • cart    object

    A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.

  • billingAddress    object

  • consignments    array[object]

  • coupons    array[object]

    Coupons applied at the checkout level.

  • orderId    string

  • shippingCostTotal    number

    Shipping cost before any discounts are applied.

  • giftWrappingCostTotal    number

    Gift wrapping cost for all items, including or excluding tax.

  • handlingCostTotal    number

    Handling cost for all consignments including or excluding tax.

  • taxTotal    number

  • taxes    array[object]

  • subtotal    number

    Subtotal of the checkout before applying item-level discounts. Tax inclusive based on the store settings.

  • grandTotal    number

    The total payable amount, before applying any store credit or gift certificate.

  • giftCertificates    array[array]

    Applied gift certificate (as a payment method).

  • createdTime    string

    Time when the cart was created.

  • updatedTime    string

    Time when the cart was last updated.

  • customerMessage    string

    Shopperʼs message provided as details for the order to be created from this cart

  • outstandingBalance    number

    grandTotal subtract the store-credit amount

  • isStoreCreditApplied    boolean

    true value indicates StoreCredit has been applied.

example

{
  "id": "29eb9b44-8f33-4e4a-9429-d0e8e24641ed",
  "cart": {
    "id": "29eb9b44-8f33-4e4a-9429-d0e8e24641ed",
    "customerId": 18,
    "email": "dwaynecole@testing.com",
    "currency": {
      "name": "US Dollars",
      "code": "USD",
      "symbol": "$",
      "decimalPlaces": 2
    },
    "isTaxIncluded": true,
    "baseAmount": 7.95,
    "discountAmount": 0,
    "cartAmount": 7.95,
    "coupons": [],
    "discounts": [
      {
        "id": "243c9ca2-22b4-417a-8b09-b3fc05778b52",
        "discountedAmount": 0
      }
    ],
    "lineItems": {
      "physicalItems": [
        {
          "id": "243c9ca2-22b4-417a-8b09-b3fc05778b52",
          "parentId": {},
          "variantId": 345,
          "productId": 174,
          "sku": "",
          "name": "1L Le Parfait Jar",
          "url": "https://{store_domain}/all/1l-le-parfait-jar/",
          "quantity": 1,
          "brand": "OFS",
          "isTaxable": true,
          "imageUrl": "https://cdn11.bigcommerce.com/s-{store_hash}/products/174/images/425/leparfaitmedium3_1024x1024_1024x1024__37756__81924.1534344526.330.500.jpg?c=2",
          "discounts": [],
          "discountAmount": 0,
          "couponAmount": 0,
          "originalPrice": 7.95,
          "listPrice": 7.95,
          "salePrice": 7.95,
          "extendedListPrice": 7.95,
          "extendedSalePrice": 7.95,
          "isShippingRequired": true,
          "giftWrapping": {},
          "addedByPromotion": false
        }
      ],
      "digitalItems": [],
      "giftCertificates": [],
      "customItems": []
    },
    "createdTime": "2019-01-10T17:18:00+00:00",
    "updatedTime": "2019-01-10T17:19:47+00:00"
  },
  "billingAddress": {
    "id": "5c377ead301c2",
    "firstName": "Dwayne",
    "lastName": "Cole",
    "email": "dwaynecole@testing.com",
    "company": "",
    "address1": "Mauna Kea Access Rd",
    "address2": "",
    "city": "Hilo",
    "stateOrProvince": "Hawaii",
    "stateOrProvinceCode": "HI",
    "country": "United States",
    "countryCode": "US",
    "postalCode": "96720",
    "phone": "8081234567",
    "customFields": []
  },
  "consignments": [
    {
      "id": "5c377ead30ac1",
      "shippingCost": 8,
      "handlingCost": 0,
      "couponDiscounts": [],
      "discounts": [],
      "lineItemIds": [
        "243c9ca2-22b4-417a-8b09-b3fc05778b52"
      ],
      "selectedShippingOption": {
        "id": "d09e05c0-3788-44df-a1bb-b6d3afdf6841",
        "type": "shipping_byweight",
        "description": "Ship by Weight",
        "imageUrl": "",
        "cost": 8,
        "transitTime": ""
      },
      "address": {
        "firstName": "Dwayne",
        "lastName": "Cole",
        "email": "dwaynecole@testing.com",
        "company": "",
        "address1": "Mauna Kea Access Rd",
        "address2": "",
        "city": "Hilo",
        "stateOrProvince": "Hawaii",
        "stateOrProvinceCode": "HI",
        "country": "United States",
        "countryCode": "US",
        "postalCode": "96720",
        "phone": "8081234567",
        "customFields": []
      }
    }
  ],
  "orderId": null,
  "shippingCostTotal": 8,
  "shippingCostBeforeDiscount": 8,
  "handlingCostTotal": 0,
  "taxTotal": 1.22,
  "coupons": [],
  "taxes": [
    {
      "name": "Tax",
      "amount": 1.22
    }
  ],
  "subtotal": 7.95,
  "grandTotal": 15.95,
  "giftCertificates": [],
  "createdTime": "2019-01-10T17:18:00+00:00",
  "updatedTime": "2019-01-10T17:19:47+00:00",
  "customerMessage": ""
}

Update Checkout Billing Address

PUT /checkouts/{checkoutId}/billing-address/{addressId}

Request

Updates an existing billing address on Checkout.

Note

  • Substitute your storefront domain for yourstore.example.com.
  • The Send a Test Request feature is not currently supported for this endpoint.

Parameters

  • store_domain in path - string
  • checkoutId in path - string - required
  • addressId in path - number - required

Body

object | application/json

  • firstName    string

  • lastName    string

  • email    string

  • company    string

  • address1    string

  • address2    string

  • city    string

  • stateOrProvince    string

    Represents state or province.

  • stateOrProvinceCode    string

  • countryCode    string
    required

    ISO 3166-1 alpha-2 country code. (See: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

  • postalCode    string

  • phone    string

  • customFields    array[object]

example

{
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "company": "string",
  "address1": "string",
  "address2": "string",
  "city": "string",
  "stateOrProvince": "string",
  "stateOrProvinceCode": "string",
  "countryCode": "string",
  "postalCode": "string",
  "phone": "string",
  "customFields": [
    {
      "fieldId": "string",
      "fieldValue": "string"
    }
  ]
}

Response

Body

object | application/json

  • id    string

  • cart    object

    A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.

  • billingAddress    object

  • consignments    array[object]

  • coupons    array[object]

    Coupons applied at the checkout level.

  • orderId    string

  • shippingCostTotal    number

    Shipping cost before any discounts are applied.

  • giftWrappingCostTotal    number

    Gift wrapping cost for all items, including or excluding tax.

  • handlingCostTotal    number

    Handling cost for all consignments including or excluding tax.

  • taxTotal    number

  • taxes    array[object]

  • subtotal    number

    Subtotal of the checkout before applying item-level discounts. Tax inclusive based on the store settings.

  • grandTotal    number

    The total payable amount, before applying any store credit or gift certificate.

  • giftCertificates    array[array]

    Applied gift certificate (as a payment method).

  • createdTime    string

    Time when the cart was created.

  • updatedTime    string

    Time when the cart was last updated.

  • customerMessage    string

    Shopperʼs message provided as details for the order to be created from this cart

  • outstandingBalance    number

    grandTotal subtract the store-credit amount

  • isStoreCreditApplied    boolean

    true value indicates StoreCredit has been applied.

example

{
  "id": "b6fbd994-61a8-4f25-9167-6ec10489c448",
  "cart": {
    "id": "b6fbd994-61a8-4f25-9167-6ec10489c448",
    "customerId": 11,
    "email": "janedoe@example.com",
    "currency": {
      "name": "US Dollars",
      "code": "USD",
      "symbol": "$",
      "decimalPlaces": 2
    },
    "isTaxIncluded": false,
    "baseAmount": 119.93,
    "discountAmount": 0,
    "cartAmount": 112.93,
    "coupons": [
      {
        "id": 1,
        "code": "S2549JM0Y",
        "displayName": "$5.00 off the order total",
        "couponType": "per_total_discount",
        "discountedAmount": 5
      }
    ],
    "discounts": [
      {
        "id": "69791a88-85c9-4c19-8042-e537621e8a55",
        "discountedAmount": 2.59
      },
      {
        "id": "ba2c619d-e6b4-48c2-8809-d88e424ed450",
        "discountedAmount": 1.06
      },
      {
        "id": "c72d6651-978d-45e5-881b-c2bb5f7ff1d5",
        "discountedAmount": 2.12
      },
      {
        "id": "6477a4a1-02cf-4287-8bf2-fd043bdd5234",
        "discountedAmount": 0.8
      },
      {
        "id": "871f1f56-4c88-43c3-a6e5-0a647d83d6ac",
        "discountedAmount": 0.43
      }
    ],
    "lineItems": {
      "physicalItems": [
        {
          "id": "69791a88-85c9-4c19-8042-e537621e8a55",
          "parentId": {},
          "variantId": 364,
          "productId": 184,
          "sku": "SMA-RED",
          "name": "Canvas Laundry Cart",
          "url": "https://{store_domain}/all/canvas-laundry-cart/",
          "quantity": 1,
          "isTaxable": true,
          "imageUrl": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.330.500.jpg?c=2",
          "discounts": [
            {
              "id": "total-coupon",
              "discountedAmount": 0.59
            },
            {
              "id": 2,
              "discountedAmount": 2
            }
          ],
          "discountAmount": 2,
          "couponAmount": 0,
          "originalPrice": 17.99,
          "listPrice": 15.99,
          "salePrice": 13.99,
          "extendedListPrice": 15.99,
          "extendedSalePrice": 13.99,
          "isShippingRequired": true,
          "giftWrapping": {},
          "addedByPromotion": false
        },
        {
          "id": "ba2c619d-e6b4-48c2-8809-d88e424ed450",
          "parentId": {},
          "variantId": 341,
          "productId": 170,
          "sku": "",
          "name": "Ceramic Measuring Spoons",
          "url": "https://{store_domain}/all/ceramic-measuring-spoons/",
          "quantity": 1,
          "isTaxable": true,
          "imageUrl": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/170/images/411/measuringsquares2_1024x1024__07108__95421.1534344522.330.500.jpg?c=2",
          "discounts": [
            {
              "id": "total-coupon",
              "discountedAmount": 1.06
            }
          ],
          "discountAmount": 0,
          "couponAmount": 0,
          "originalPrice": 25,
          "listPrice": 25,
          "salePrice": 25,
          "extendedListPrice": 25,
          "extendedSalePrice": 25,
          "isShippingRequired": true,
          "giftWrapping": {},
          "addedByPromotion": false
        },
        {
          "id": "c72d6651-978d-45e5-881b-c2bb5f7ff1d5",
          "parentId": {},
          "variantId": 376,
          "productId": 158,
          "sku": "SKU-A0C8A203",
          "name": "Chambray Towel",
          "url": "https://{store_domain}/all/chambray-towel/",
          "quantity": 1,
          "isTaxable": true,
          "imageUrl": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.330.500.jpg?c=2",
          "discounts": [
            {
              "id": "total-coupon",
              "discountedAmount": 2.12
            }
          ],
          "discountAmount": 0,
          "couponAmount": 0,
          "originalPrice": 49.99,
          "listPrice": 49.99,
          "salePrice": 49.99,
          "extendedListPrice": 49.99,
          "extendedSalePrice": 49.99,
          "isShippingRequired": true,
          "giftWrapping": {},
          "addedByPromotion": false
        }
      ],
      "digitalItems": [
        {
          "id": "6477a4a1-02cf-4287-8bf2-fd043bdd5234",
          "parentId": {},
          "variantId": 360,
          "productId": 189,
          "name": "Gather Journal Issue 7 - Digital",
          "url": "https://{store_domain}/all/gather-journal-issue-7/",
          "quantity": 1,
          "isTaxable": true,
          "imageUrl": "https://cdn8.bigcommerce.com/s-id30h7ohwf/products/189/images/465/gather_1024x1024__17195__82620.1534344540.330.500.jpg?c=2",
          "discounts": [
            {
              "id": "total-coupon",
              "discountedAmount": 0.8
            }
          ],
          "discountAmount": 0,
          "couponAmount": 0,
          "originalPrice": 18.95,
          "listPrice": 18.95,
          "salePrice": 18.95,
          "extendedListPrice": 18.95,
          "extendedSalePrice": 18.95,
          "isShippingRequired": false,
          "type": "digital"
        }
      ],
      "giftCertificates": [
        {
          "id": "871f1f56-4c88-43c3-a6e5-0a647d83d6ac",
          "name": "$10.00 Gift Certificate",
          "theme": "Celebration",
          "amount": 10,
          "taxable": false,
          "sender": {
            "name": "Jane Doe",
            "email": "janedoe@example.com"
          },
          "recipient": {
            "name": "John Doe",
            "email": "johndoe@example.com"
          },
          "message": "Thank you!",
          "type": "giftCertificate"
        }
      ]
    },
    "createdTime": "2018-09-18T15:48:26+00:00",
    "updatedTime": "2018-09-18T16:59:45+00:00"
  },
  "billingAddress": {
    "id": "5ba11e4a10fb5",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "janedoe@example.com",
    "company": "",
    "address1": "123 Main Street",
    "address2": "",
    "city": "Austin",
    "stateOrProvince": "Texas",
    "stateOrProvinceCode": "TX",
    "country": "United States",
    "countryCode": "US",
    "postalCode": "78751",
    "phone": "1234567890",
    "customFields": [
      {
        "fieldId": "field_25",
        "fieldValue": "Leave in backyard"
      }
    ]
  },
  "consignments": [
    {
      "id": "5ba121929619b",
      "shippingCost": 69.94,
      "handlingCost": 0,
      "couponDiscounts": [],
      "discounts": [],
      "lineItemIds": [
        "69791a88-85c9-4c19-8042-e537621e8a55",
        "ba2c619d-e6b4-48c2-8809-d88e424ed450",
        "c72d6651-978d-45e5-881b-c2bb5f7ff1d5"
      ],
      "selectedShippingOption": {
        "id": "bb3c818f-17ce-46fe-9475-65933095da0d",
        "type": "shipping_upsready",
        "description": "UPS® (UPS Next Day Air®)",
        "imageUrl": "",
        "cost": 69.94,
        "transitTime": "1 business day"
      },
      "address": {
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "janedoe@example.com",
        "company": "",
        "address1": "123 Main Street",
        "address2": "",
        "city": "Austin",
        "stateOrProvince": "Texas",
        "stateOrProvinceCode": "TX",
        "country": "United States",
        "countryCode": "US",
        "postalCode": "78751",
        "phone": "1234567890",
        "customFields": [
          {
            "fieldId": "field_25",
            "fieldValue": "Leave in backyard"
          }
        ]
      }
    }
  ],
  "orderId": null,
  "shippingCostTotal": 69.94,
  "shippingCostBeforeDiscount": 69.94,
  "handlingCostTotal": 0,
  "taxTotal": 28.62,
  "coupons": [
    {
      "id": 1,
      "code": "S2549JM0Y",
      "displayName": "$5.00 off the order total",
      "couponType": 2,
      "discountedAmount": 5
    }
  ],
  "taxes": [
    {
      "name": "Store Tax",
      "amount": 28.62
    }
  ],
  "subtotal": 117.93,
  "grandTotal": 211.49,
  "giftCertificates": [],
  "createdTime": "2018-09-18T15:48:26+00:00",
  "updatedTime": "2018-09-18T16:59:45+00:00",
  "customerMessage": "Thank you, BigCommerce"
}