openapi: 3.0.0 info: title: BigCommerce Abandoned Cart Emails Carts (Single) API version: 3.0.0 termsOfService: https://www.bigcommerce.com/terms description: Abandoned Cart Emails V3 API managing Handlebars-based emails. contact: name: BigCommerce url: https://www.bigcommerce.com email: support@bigcommerce.com servers: - url: https://api.bigcommerce.com/stores/{store_hash}/v3 variables: store_hash: default: store_hash description: Permanent ID of the BigCommerce store. description: BigCommerce API Gateway security: - X-Auth-Token: [] tags: - name: Carts (Single) paths: /carts: parameters: - $ref: '#/components/parameters/Accept' post: description: "Creates a **Cart**. \n\n**Required Fields**\n\n|Field|Details|\n|-|-|\n|`line_item`|Specifies a line item.| \n|`custom_items`|Specifies a custom item. Only required if adding a custom item to the cart.|\n|`gift_certificates`|Specifies a gift certificate. Only required if adding a gift certificate to the cart.|\n\n**Usage Notes**\n\n* A **cart** `id` (UUID) is returned in the response.\n* A **cart** `id` is the same as a **checkout** `id`.\n* A cart can be created by adding an existing **catalog item** or a **custom item**.\n* Carts are valid for **30 days** from the **last modification** (this includes creating the cart or editing the cart).\n* If a product has modifiers, use the `option_selections` array to describe the **modifier** selection(s).\n* The format and data type of a cart’s `option_value` are defined by the `value_data` object of a product’s [variant option value](/docs/rest-catalog/product-variant-options/values), [modifier value](/docs/rest-catalog/product-modifiers/values), or a combination of both.\n* Redirect URLs can only be generated from carts that were created using the **REST Management API**. \n* To get cart `redirect_urls` in the response, append the following query parameter to the request URL: `include=redirect_urls`. Redirect URLs point to either a shared checkout domain or a channel-specific domain, depending on the storefront configuration.\n* To restore a cart that was created by a shopper or through a Storefront API, first recreate the cart using the **REST Management API**.\n* To get cart `promotions` in the response, append the following query parameter to the request URL: `include=promotions.banners`." parameters: - name: include in: query description: '* `redirect_urls`: Create a direct link to a cart. This can be used for the /POST request for carts. * `line_items.physical_items.options`: The cart returns an abbreviated result. Use this to return physical items product options. To return the extended cart object, use in a /POST request. * `line_items.digital_items.options`: The cart returns an abbreviated result. Use this to return digital items product options. To return the extended cart object, use in a /POST request. * `promotions.banners`: Returns a list of eligible banners.' schema: type: string enum: - redirect_urls - line_items.physical_items.options - line_items.digital_items.options - promotions.banners - $ref: '#/components/parameters/ContentType' requestBody: content: application/json: schema: $ref: '#/components/schemas/CartCreatePostData' examples: Simple Product: summary: Creating a cart by adding a simple product without option selections. value: customer_id: 0 line_items: - quantity: 2 product_id: 126 list_price: 5 name: calendar channel_id: 1 currency: code: USD locale: en-US Cart with a variant: summary: Creating a cart with a product that can be specified purely by a variant, without any other required options. value: customer_id: 0 line_items: - quantity: 2 product_id: 118 list_price: 25 variant_id: 140 name: قميص option_selections: - option_id: 125 option_value: 127 name: بحجم value: صغير channel_id: 1 currency: code: JOD locale: ar-JO Cart with date option: summary: Creating a cart using a date option. value: line_items: - quantity: 1 product_id: 128 variant_id: 144 option_selections: - option_id: 147 option_value: '{“día”:”01”, “mes”:”02”, “año”:”2020”}' name: calendario value: 2023 currency: code: MXN locale: es-MX Cart with variant, a checkbox, and a pick list modifier: summary: Creating a cart with a variant, a checkbox, and an added picklist modifier. value: customer_id: 0 line_items: - quantity: 1 variant_id: 141 product_id: 118 list_price: 30 name: shirt option_selections: - name: Color value: Red option_id: 133 option_value: 149 - name: Add a $5 Donation value: 'No' option_id: 126 option_value: 129 channel_id: 1 currency: code: AUD locale: en-AU Custom item: summary: Creating a cart using a custom item. value: customer_id: 0 line_items: [] custom_items: - sku: custom-item-sku name: table quantity: 1 list_price: 30 gift_wrapping: wrap_together: true wrap_details: - id: 0 message: Happy Birthday gift_certificates: - name: Tobi Day theme: birthday.html amount: 1 quantity: 1 sender: name: Brandi Tyler email: Brandi.Tyler@mail.com recipient: name: Tobi Day email: Tobi.Day@mail.com message: Happy Birthday channel_id: 1 currency: code: usd locale: en-US description: '' required: true x-examples: Simple Product: line_items: - quantity: 5 product_id: 191 Create a Cart with a Variant: line_items: - quantity: 2 product_id: 107 variant_id: 185 Create a Cart using Date Option: line_items: - quantity: 5 product_id: 191 variant_id: 185 option_selections: - option_id: 440 option_value: 1743570000 With a Variant of Checkbox and Picklist: line_items: - quantity: 1 product_id: 77 option_selections: - option_id: 120 option_value: 69 - option_id: 121 option_value: 10 - option_id: 124 option_value: 106 - option_id: 122 option_value: Hello - option_id: 123 option_value: 104 Custom Item: custom_items: - sku: abc-123 name: Custom Product quantity: 1 list_price: 10 Options Selections: line_items: - quantity: 5 product_id: 118 variant_id: 115 option_selections: - option_id: 121 option_value: 10 name: Size nameId: 125 value: Small valueId: 125 tags: - Carts (Single) responses: '201': $ref: '#/components/responses/CartResponse' summary: BigCommerce Create a Cart operationId: createCart /carts/{cartId}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/cartId' get: description: Returns a storeʼs *Cart*. parameters: - name: include in: query description: '* `redirect_urls`: Create a direct link to a cart. This can be used for the /POST request for carts. * `line_items.physical_items.options`: The cart returns an abbreviated result. Use this to return physical items product options. To return the extended cart object, use in a /POST request. * `line_items.digital_items.options`: The cart returns an abbreviated result. Use this to return digital items product options. To return the extended cart object, use in a /POST request. * `promotions.banners`: Returns a list of eligible banners.' schema: type: string enum: - redirect_urls - line_items.physical_items.options - line_items.digital_items.options - promotions.banners tags: - Carts (Single) responses: '200': $ref: '#/components/responses/CartResponse' '404': description: Cart not found. summary: BigCommerce Get a Cart operationId: getCart put: description: 'Updates a *Cartʼs* `customer_id`. **Notes** Changing the *Cart* `customer_id` will remove any promotions or shipping calculations on the *Cart*. These are tied to the customer depending on cart conditions and any customer groups. ' parameters: - name: include in: query description: '* `redirect_urls`: Create a direct link to a cart. This can be used for the /POST request for carts. * `line_items.physical_items.options`: The cart returns an abbreviated result. Use this to return physical items product options. To return the extended cart object, use in a /POST request. * `line_items.digital_items.options`: The cart returns an abbreviated result. Use this to return digital items product options. To return the extended cart object, use in a /POST request. * `promotions.banners`: Returns a list of eligible banners.' schema: type: string enum: - redirect_urls - line_items.physical_items.options - line_items.digital_items.options - promotions.banners - $ref: '#/components/parameters/ContentType' requestBody: content: application/json: schema: $ref: '#/components/schemas/CartUpdatePutRequestData' example: customer_id: 5 required: true tags: - Carts (Single) responses: '201': $ref: '#/components/responses/CartResponse' summary: BigCommerce Update Customer ID operationId: updateCart delete: description: Deletes a *Cart*. Once a *Cart* has been deleted it can’t be recovered. tags: - Carts (Single) responses: '204': description: '' summary: BigCommerce Delete a Cart operationId: deleteCart components: parameters: Accept: name: Accept in: header required: true description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. schema: type: string default: application/json ContentType: name: Content-Type in: header required: true schema: type: string default: application/json cartId: name: cartId in: path description: The identifier of a specific cart. required: true schema: type: string format: UUID schemas: ItemCustomGet: type: object title: Item Custom description: 'Add a custom item to the shopperʼs cart. * Custom items are not added to the catalog. * The price should be set to match the store settings for taxes.' x-internal: false properties: id: type: string description: ID of the custom item. sku: type: string description: SKU of the custom item. name: type: string description: Name of the item. quantity: type: string list_price: type: string description: Specifies the price of the item. This value can include or exclude tax, depending on the store setup. Cart_Full: description: A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data. type: object title: Cart_Full x-internal: false properties: id: description: Cart ID, provided after creating a cart with a POST request. type: string format: UUID parent_id: type: string description: Bundled items will have the ID of their parent item. customer_id: description: ID of the customer to which the cart belongs. type: integer email: description: The cart’s email. This is the same email that is used in the billing address. type: string currency: type: object description: The currency. This is the same for both the cart and its subsequent checkout. title: Currency properties: code: type: string format: ISO-4217 description: The [transactional currency](/docs/rest-management/currencies#definitions) code for the cart, formatted as an [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) string. example: usd tax_included: type: boolean base_amount: type: number description: Sum of cart line-item amounts before cart-level discounts, coupons, or taxes. discount_amount: type: number description: Order-based discounted amount only - Excludes coupon discounts and product-based discounts. cart_amount: type: number description: Sum of cart line-item amounts minus cart-level discounts and coupons. This amount includes taxes (where applicable). coupons: type: array items: $ref: '#/components/schemas/AppliedCoupon' discounts: type: array items: type: object title: Applied Discount description: "Example as part of a cart response:\n\n```\n \"discounts\": [\n {\n \"id\": 2,\n \"discounted_amount\": 2\n },\n {\n \"id\": \"coupon\",\n \"discounted_amount\": 0.42\n }\n ]\n```" properties: id: type: string description: ID of the applied discount. example: coupon discounted_amount: type: number description: The discounted amount. line_items: $ref: '#/components/schemas/LineItemsGet' created_time: type: string format: ISO-8601 description: Time when the cart was created. updated_time: type: string format: ISO-8601 description: Time when the cart was last updated. channel_id: type: integer description: The channel ID. If no channel is specified, defaults to 1. locale: type: string description: Locale of the cart. Accepts strings of format `xx` or `xx-YY`. Uses the [ISO-639 standard](https://www.iso.org/iso-639-language-codes.html) format. format: ISO-639 promotions: type: object description: This is available only when "include=promotions.banners" is presented in the URL. properties: banners: title: Banner type: object properties: id: description: ID of the promotion. type: string type: description: Type of the banner. type: string page: description: An array of the locations where the banner will display. type: array items: type: string text: description: Text of the banner. type: string CartUpdatePutRequestData: type: object properties: customer_id: type: integer title: Cart Update Put Request Data x-internal: false LineItemsGet: title: LineItemsGet type: object properties: physical_items: type: array items: $ref: '#/components/schemas/ItemPhysicalGet' digital_items: type: array items: $ref: '#/components/schemas/ItemDigitalGet' gift_certificates: type: array items: $ref: '#/components/schemas/ItemGiftCertificateGet' custom_items: type: array items: $ref: '#/components/schemas/ItemCustomGet' description: '`GET`' CartCreatePostData: type: object title: Cart Create Post Data x-internal: false properties: customer_id: type: integer line_items: type: array items: anyOf: - $ref: '#/components/schemas/cart_PostVariant' - $ref: '#/components/schemas/cart_PostModifier' custom_items: $ref: '#/components/schemas/cart_PostCustomItem' gift_certificates: type: array items: type: object title: Line Item Gift Certificate Request Data properties: name: type: string description: Given name for the gift certificate line item. theme: type: string description: The theme of the gift certificate. enum: - birthday.html - boy.html - celebration.html - christmas.html - general.html - girl.html amount: type: number minimum: 1 maximum: 1000 quantity: type: integer minimum: 1 sender: title: Contact Entity type: object properties: name: type: string email: type: string recipient: title: Contact Entity type: object properties: name: type: string email: type: string message: type: string maximum: 200 description: Message shown to recipient, as provided by sender. required: - name - theme - amount - quantity - sender - recipient channel_id: type: integer description: The Channel ID. If no channel is specified, defaults to 1. currency: type: object properties: code: type: string format: ISO-4217 description: The [transactional currency](/docs/rest-management/currencies#definitions) code for the cart, formatted as an [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) string. This code is required when multi-currency is enabled. Passing a non-transactional display currency will result in a `400` error. example: usd locale: type: string description: The locale of the cart. Accepts strings of format `xx` or `xx-YY`. Uses the [ISO-639 standard](https://www.iso.org/iso-639-language-codes.html) format. format: ISO-639 example: en-US description: '' AppliedCoupon: title: Applied Coupon type: object description: '|Type `int`|Type Name| |-|-| |`0`|`per_item_discount`| |`1`|`percentage_discount`| |`2`|`per_total_discount`| |`3`|`shipping_discount`| |`4`|`free_shipping`| |`5`|`promotion`|' x-internal: false properties: code: description: The coupon code. type: string id: description: The coupon ID. (read-only) type: string readOnly: true coupon_type: description: 'Key name to identify the type of coupon. type 0: per_item_discount type 1: percentage_discount type 2: per_total_discount type 3: shipping_discount type 4: free_shipping type 5: promotion' type: string enum: - '0' - '1' - '2' - '3' - '4' - '5' readOnly: true discounted_amount: description: The discounted amount applied within a given context. type: number format: double readOnly: true required: - code ItemGiftCertificateGet: type: object title: Item Gift Certificate x-internal: false properties: id: type: string name: type: string description: Name provided for the gift certificate that will appear in the control panel. theme: type: string description: The theme of the gift certificate. The following options are available:`birthday.html`, `boy.html`, `celebration.html`, `christmas.html`, `general.html`, and `girl.html`. amount: type: number description: Value must be between 1.00 and 1,000.00 in the store’s default currency. is_taxable: type: boolean sender: title: Contact Entity type: object properties: name: type: string email: type: string recipient: title: Contact Entity type: object properties: name: type: string email: type: string message: type: string description: The message included in the gift certificate is limited to 200 characters. ItemDigitalGet: allOf: - title: Base Item properties: id: type: string description: The line-item ID. example: 6e193ce6-f327-4dcc-b75e-72cf6738525e variant_id: type: number description: The ID of the variant. Required in the /PUT or /POST request if the product has variants. example: 358 product_id: type: number description: The ID of the product. Required in a /POST request. example: 12 sku: type: string example: SMGREEN description: SKU of the variant. name: type: string description: The item’s product name. example: T-Shirt url: description: The product URL. type: string format: uri example: http://your-store-url.mybigcommerce.com/your-product/ quantity: type: number example: 5 description: Quantity of this item in the cart. is_taxable: type: boolean example: false description: Boolean value that specifies whether the item is taxable. image_url: type: string format: uri example: https://pathtoproductimage/ProductDefault.png description: Image of the product or variant. discounts: type: array items: type: object title: Applied Discount description: "Example as part of a cart response:\n\n```\n \"discounts\": [\n {\n \"id\": 2,\n \"discounted_amount\": 2\n },\n {\n \"id\": \"coupon\",\n \"discounted_amount\": 0.42\n }\n ]\n```" properties: id: oneOf: - type: string - type: number discounted_amount: type: number description: The discounted amount. coupons: oneOf: - type: number - type: array items: type: object title: Applied Coupon properties: id: type: integer example: 6 description: ID of the coupon. code: type: string example: KV56053388J description: The coupon code. Required in a /POST request. name: type: string example: Percentage off description: Name given to the coupon in the control panel. discountType: type: integer description: 'The discount type. - type 0: per_item_discount - type 1: percentage_discount - type 2: per_total_discount - type 3: shipping_discount - type 4: free_shipping ' example: 3 enum: - 0 - 1 - 2 - 3 - 4 discountAmount: type: integer description: The amount of the discount based on the coupon. For example, 3 percent off will show a 3. example: 3 expiresDate: type: integer example: 0 description: Returns 0 if no expiration date has been set. totalDiscount: type: number example: 4.19 description: The total amount of all discounts applied to the cart. required: - code discount_amount: type: number description: The total value of all discounts applied to this item. This includes coupons and cart-level discounts. example: 4 coupon_amount: type: number description: The total value of all coupons applied to this item. original_price: type: number description: An item’s original price is the same as the product default price in the admin panel. list_price: type: number description: The net item price before discounts and coupons. BigCommerce derives an item’s list price from the product default price or, if applicable, the sale price configured in the admin panel. sale_price: type: number description: Item’s price after all discounts are applied. (The final price before tax calculation.) extended_list_price: type: number description: List price of the item multiplied by the quantity. extended_sale_price: type: number description: Sale price of the item multiplied by the quantity. options: description: The list of selected options for this product. type: array items: type: object title: Product Option properties: name: type: string description: The product option name; for example, Color or Size. nameId: type: number description: The product option identifier. value: type: string description: The product option value; for example, Red or Medium. valueId: type: number description: The product option value identifier in number format. example: 128 - properties: download_file_urls: description: URLs to download all product files. type: array items: type: string format: url download_page_url: description: The URL for the combined downloads page. type: string format: url download_size: description: Specifies the combined download size of all files in human-readable style; for example, `30MB`. type: string type: object title: '' description: '' cart_PostModifier: type: object title: Item with modifier properties: quantity: type: number product_id: type: number list_price: type: number description: Optional price override. name: type: string description: Optionally, provide a value to override the product name. option_selections: type: array description: Needed for Catalog V2. items: type: object properties: option_id: type: integer option_value: type: integer name: type: string description: Override for the selected option or modifier name. value: type: string description: Override for the selected option value. nameId: type: integer valueId: type: integer required: - quantity - product_id description: Product with a modifier. x-internal: false x-examples: example-1: - quantity: 0 product_id: 0 list_price: 0 name: string option_selections: - option_id: 0 option_value: 0 name: string value: string name_id: 0 value_id: 0 cart_PostCustomItem: type: array title: Custom item x-internal: false items: type: object properties: sku: type: string name: type: string minLength: 1 maxLength: 250 quantity: type: number list_price: type: number x-examples: example-1: - sku: string name: string quantity: 0 list_price: 0 cart_PostVariant: type: object title: Item with variant x-internal: false properties: quantity: type: number product_id: type: number list_price: type: number description: Optional price override. variant_id: type: number description: Variant ID. Exists only in Catalog V3. name: type: string description: Optionally, provide a value to override the product name. gift_wrapping: type: object properties: wrap_together: type: boolean description: Boolean value that specifies whether items whether items should be wrapped together or wrapped individually. example: true wrap_details: type: array description: Details for the gift wrapping option selected. This can be specified for each line item. items: type: object properties: id: type: number description: Identifier of the gift wrapping option selected. example: 0 message: type: string description: Custom gift message. example: Happy Birthday required: - quantity - product_id description: Product with a variant. x-examples: example-1: quantity: 0 product_id: 0 list_price: 0 variant_id: 0 name: string gift_wrapping: wrap_together: true wrap_details: - id: 0 message: Happy Birthday ItemPhysicalGet: allOf: - type: object title: Base Item properties: id: type: string description: The line-item ID. example: 6e193ce6-f327-4dcc-b75e-72cf6738525e variant_id: type: number description: The ID of the variant. Required in the /PUT or /POST request if the product has variants. example: 358 product_id: type: number description: The ID of the product. Required in a /POST request. example: 12 sku: type: string example: SMGREEN description: SKU of the variant. name: type: string description: The item’s product name. example: T-Shirt weight: type: number description: The weight is displayed here if the item has a custom dimension. example: 1.2 dimensions: type: object properties: height: type: number description: The height is displayed here if the item has a custom dimension. example: 2 width: type: number description: The width is displayed here if the item has a custom dimension. example: 2.1 depth: type: number description: The depth is displayed here if the item has a custom dimension. example: 2.2 url: description: The product URL. type: string format: uri example: http://your-store-url.mybigcommerce.com/your-product/ quantity: type: number example: 5 description: Quantity of this item in the cart. is_taxable: type: boolean example: false description: Boolean value that specifies whether the item is taxable. image_url: type: string format: uri example: https://pathtoproductimage/ProductDefault.png description: Image of the product or variant. discounts: type: array items: type: object title: Applied Discount description: "Example as part of a cart response:\n\n```\n \"discounts\": [\n {\n \"id\": 2,\n \"discounted_amount\": 2\n },\n {\n \"id\": \"coupon\",\n \"discounted_amount\": 0.42\n }\n ]\n```" properties: id: oneOf: - type: string - type: number discounted_amount: type: number description: The discounted amount. coupons: oneOf: - type: number - type: array items: type: object title: Applied Coupon properties: id: type: integer example: 6 description: ID of the coupon. code: type: string example: KV56053388J description: The coupon code. Required in a /POST request. name: type: string example: Percentage off description: Name given to the coupon in the control panel. discountType: type: integer description: 'The discount type. - type 0: per_item_discount - type 1: percentage_discount - type 2: per_total_discount - type 3: shipping_discount - type 4: free_shipping' example: 3 enum: - 0 - 1 - 2 - 3 - 4 discountAmount: type: integer description: The amount of the discount based on the coupon. For example, 3 percent off will show a 3. example: 3 expiresDate: type: integer example: 0 description: Returns 0 if no expiration date has been set. totalDiscount: type: number example: 4.19 description: The total amount of all discounts applied to the cart. required: - code discount_amount: type: number description: The total value of all discounts applied to this item. This includes coupons and cart-level discounts. example: 4 coupon_amount: type: number description: The total value of all coupons applied to this item. original_price: type: number description: An item’s original price is the same as the product default price in the admin panel. list_price: type: number description: The net item price before discounts and coupons are applied. BigCommerce derives an item’s list price from the product default price or, if applicable, the sale price configured in the admin panel. sale_price: type: number description: Price of the item after all discounts are applied. (The final price before tax calculation.) extended_list_price: type: number description: List price of the item multiplied by the quantity. extended_sale_price: type: number description: Sale price of the item multiplied by the quantity. options: description: The list of selected options for this product. type: array items: type: object title: Product Option properties: name: type: string description: The product option name; for example, Color or Size. nameId: type: number example: 151 description: The product option identifier. value: type: string description: The product option value; for example, Red or Medium. valueId: oneOf: - type: number example: 128 - type: string example: '1259' description: The product option value identifier in number format. gift_wrapping: description: The gift wrapping details for this item. type: object properties: name: type: string example: Gift Wrap 1 message: type: string example: Happy Birthday! amount: type: number format: float example: 1.99 required: - variant_id - product_id - quantity - {} title: '' description: '' responses: CartResponse: description: '' content: application/json: schema: $ref: '#/components/schemas/Cart_Full' examples: {} securitySchemes: X-Auth-Token: name: X-Auth-Token description: '### OAuth scopes | UI Name | Permission | Parameter | |:--|:--|:-| | Information & Settings | read-only | `store_v2_information_read_only`| | Information & Settings | modify | `store_v2_information` | ### 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](/docs/start/authentication/api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).' type: apiKey in: header