openapi: 3.0.0 info: title: BigCommerce Abandoned Cart Emails Items 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: Items paths: /carts/{cartId}/items: parameters: - $ref: '#/components/parameters/cartId' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContentType' post: description: "Adds line item to the *Cart*.\n\n**Usage Notes**\n\nTo add a custom item use `custom_items`. \n\nOverriding a product’s `list_price` will make that item ineligible for V3 product level promotions.\n\nIf a product has modifiers, omit the `variant_id` and instead use the `option_selections` array to describe both the **variant** and the **modifier** selections.\n\nPlease note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results." 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 requestBody: content: application/json: schema: $ref: '#/components/schemas/Cart_Line_Item_Update_Post' examples: Example 1: value: line_items: - quantity: 2 product_id: 77 list_price: 12.5 option_selections: - option_id: 8 option_value: 'Yes' gift_certificates: - name: Happy Birthday theme: birthday.html amount: 50 quantity: 1 sender: name: Jane Does email: janedoe@example.com recipient: name: Jane Does email: janedoe@example.com message: Happy Birthday Jane! 'Example 2: Custom Item': value: custom_items: - sku: abc-123 name: Custom Product quantity: 1 list_price: 10 required: true tags: - Items responses: '201': $ref: '#/components/responses/CartResponse' summary: BigCommerce Add Cart Line Items operationId: addCartLineItems /carts/{cartId}/items/{itemId}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/cartId' - name: itemId in: path required: true schema: type: string format: number put: description: "Updates an existing, single line item in the *Cart*. \n\n**Notes**\n\nCurrently, only updating `list_price` and `quantity` are supported. Updating a product’s `list_price` will make that item ineligible for V3 product-level promotions. \n\nIf the product has modifiers, omit the `variant_id` and instead use the `option_selections` array to describe both the **variant** and the **modifier** selections.\n\nIf a variant needs to be changed or updated, the product will need to be removed and re-added to the cart with the correct variants using the **Add Cart Line Items** endpoint.\n\n`custom_items` cannot be updated via the API at this time. To update your cart, add a new updated custom item and delete the outdated one. If your cart contains only one line item, perform the add operation before the delete operation.\n\nDeleting all line items from the cart will invalidate the cart. \n\nPlease note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results." 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/Cart_Line_Item_Update_Put' required: true tags: - Items responses: '200': $ref: '#/components/responses/CartResponse' summary: BigCommerce Update Cart Line Item operationId: updateCartLineItem delete: description: "Deletes a *Cart* line item. \n\n**Notes**\n\nRemoving the last `line_item` in the *Cart* deletes the *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: - Items responses: '200': description: 'NOTE: Discounted line items are re-evaluated on cart actions and may be automatically added back to your cart with a new line item ID to satisfy promotional requirements.' content: application/json: schema: $ref: '#/components/schemas/Cart_Full' examples: response: value: data: id: bc218c65-7a32-4ab7-8082-68730c074d02 customer_id: 11 email: '' currency: code: USD tax_included: false base_amount: 189.75 discount_amount: 0 cart_amount: 212.81 coupons: [] line_items: physical_items: - id: 6e193ce6-f327-4dcc-b75e-72cf6738525e parent_id: {} variant_id: 362 product_id: 191 sku: '' name: Openhouse No. 3 url: http://id30h7ohwf.mybigcommerce.com/all/openhouse-no-3/ quantity: 5 taxable: true image_url: https://cdn8.bigcommerce.com/s-id30h7ohwf/products/191/images/475/openhousevol3_1024x1024__59692__16355.1534344544.330.500.jpg?c=2 discounts: [] coupons: [] discount_amount: 0 coupon_amount: 0 original_price: 27.95 list_price: 27.95 sale_price: 27.95 extended_list_price: 139.75 extended_sale_price: 139.75 is_require_shipping: true options: - name: Add a $5 Donation nameId: 82 value: 'No' valueId: 186 digital_items: [] custom_items: - extended_list_price: 5.99 id: 78239b69-1952-4c35-9d58-ea30158b4e39 list_price: 5.99 name: Rope Toy quantity: 1 sku: ROPE-TOY gift_certificates: - id: 6e38bbc2-8873-472c-a452-8bd4aaea5d3a name: Happy Birthday theme: birthday.html amount: 50 quantity: 1 taxable: false sender: name: Jane Does email: janedoe@example.com recipient: name: Jane Does email: janedoe@example.com message: Happy Birthday Jane! created_time: '2018-09-17T14:27:39.000Z' updated_time: '2018-09-17T14:53:40.000Z' meta: {} '204': description: If the action’s result is an empty cart, the cart is automatically deleted. summary: BigCommerce Delete Cart Line Item operationId: deleteCartLineItem 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 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`' Cart_Line_Item_Update_Put: type: object title: Cart_Line_Item_Update_Put x-internal: false properties: line_item: oneOf: - $ref: '#/components/schemas/cart_PostVariant' - $ref: '#/components/schemas/cart_PostModifier' gift_certificates: type: array items: type: object title: Line Item Gift Certificate Request Data properties: name: type: string description: Given name for a 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 maxLength: 200 description: Message shown to recipient, as provided by sender. required: - name - theme - amount - quantity - sender - recipient custom_items: $ref: '#/components/schemas/cart_PostCustomItem' Cart_Line_Item_Update_Post: type: object title: Cart_Line_Item_Update_Post x-internal: false properties: line_items: oneOf: - items: $ref: '#/components/schemas/cart_PostVariant' - items: $ref: '#/components/schemas/cart_PostModifier' type: array gift_certificates: type: array items: type: object title: Line Item Gift Certificate Request Data properties: name: type: string description: Given name for 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 custom_items: $ref: '#/components/schemas/cart_PostCustomItem' 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. 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 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_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: '' 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 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