{"files":{"SKILL.md":"---\nname: carts\ndescription: \"Carts API skill. Use when working with Carts for carts. Covers 21 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# Carts\n\n## Auth\nApiKey X-Auth-Token in header\n\n## Base URL\nhttps://api.bigcommerce.com/stores/{store_hash}/v3\n\n## Setup\n1. Set your API key in the appropriate header\n2. GET /carts/settings -- get global cart settings\n3. POST /carts -- create first cart\n\n## Endpoints\n21 endpoints across 1 group. See references/api-spec.lap for full details.\n\n### Carts\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /carts | Create a Cart |\n| POST | /carts/{cartId}/items | Add Cart Line Items |\n| POST | /carts/{cartId}/redirect_urls | Create Cart Redirect URL |\n| PUT | /carts/{cartId}/items/{itemId} | Update Cart Line Item |\n| DELETE | /carts/{cartId}/items/{itemId} | Delete Cart Line Item |\n| GET | /carts/{cartId} | Get a Cart |\n| PUT | /carts/{cartId} | Update Customer ID |\n| DELETE | /carts/{cartId} | Delete a Cart |\n| GET | /carts/settings | Get Global Cart Settings |\n| PUT | /carts/settings | Update Global Cart Settings |\n| GET | /carts/settings/channels/{channel_id} | Get Channel Cart Settings |\n| PUT | /carts/settings/channels/{channel_id} | Update Channel Cart Settings |\n| GET | /carts/{cart_id}/metafields | Get Cart Metafields |\n| POST | /carts/{cart_id}/metafields | Create a Cart Metafield |\n| GET | /carts/{cart_id}/metafields/{metafield_id} | Get a Cart Metafield |\n| PUT | /carts/{cart_id}/metafields/{metafield_id} | Update a Cart Metafield |\n| DELETE | /carts/{cart_id}/metafields/{metafield_id} | Delete a Metafield |\n| GET | /carts/metafields | Get All Cart Metafields |\n| POST | /carts/metafields | Create multiple Metafields |\n| PUT | /carts/metafields | Update multiple Metafields |\n| DELETE | /carts/metafields | Delete multiple Metafields |\n\n## Common Questions\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"Create a cart?\" -> POST /carts\n- \"Create a item?\" -> POST /carts/{cartId}/items\n- \"Create a redirect_url?\" -> POST /carts/{cartId}/redirect_urls\n- \"Update a item?\" -> PUT /carts/{cartId}/items/{itemId}\n- \"Delete a item?\" -> DELETE /carts/{cartId}/items/{itemId}\n- \"Get cart details?\" -> GET /carts/{cartId}\n- \"Update a cart?\" -> PUT /carts/{cartId}\n- \"Delete a cart?\" -> DELETE /carts/{cartId}\n- \"List all settings?\" -> GET /carts/settings\n- \"Get channel details?\" -> GET /carts/settings/channels/{channel_id}\n- \"Update a channel?\" -> PUT /carts/settings/channels/{channel_id}\n- \"List all metafields?\" -> GET /carts/{cart_id}/metafields\n- \"Create a metafield?\" -> POST /carts/{cart_id}/metafields\n- \"Get metafield details?\" -> GET /carts/{cart_id}/metafields/{metafield_id}\n- \"Update a metafield?\" -> PUT /carts/{cart_id}/metafields/{metafield_id}\n- \"Delete a metafield?\" -> DELETE /carts/{cart_id}/metafields/{metafield_id}\n- \"How to authenticate?\" -> See Auth section above\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Paginated endpoints accept limit/offset or cursor parameters\n- Create/update endpoints return the modified resource on success\n- Error responses include status codes and descriptions in the spec\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Carts\n@base https://api.bigcommerce.com/stores/{store_hash}/v3\n@auth ApiKey X-Auth-Token in header\n@endpoints 21\n@hint download_for_search\n@toc carts(21)\n\n@endpoint POST /carts\n@desc Create a Cart\n@required {Content-Type: str=application/json}\n@optional {include: [str] # * `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., customer_id: int, line_items: [any], custom_items: [map{sku: str, name: str, quantity: num, list_price: num, image_url: str(uri)}], gift_certificates: [map{name!: str, theme!: str, amount!: num, quantity!: int, sender!: map, recipient!: map, message: str}], channel_id: int # The Channel ID. If no channel is specified, defaults to 1., currency: map{code: str(ISO-4217)}, locale: str(ISO-639) # 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.}\n@returns(201) {data: map{id: str(UUID), customer_id: int, channel_id: int, email: str, currency: map{code: str(ISO-4217)}, tax_included: bool, base_amount: num, discount_amount: num, manual_discount_amount: num, cart_amount: num, coupons: [map], discounts: [map], line_items: map{physical_items: [any], digital_items: [any], gift_certificates: [map], custom_items: [map]}, created_time: str(ISO-8601), updated_time: str(ISO-8601), locale: str(ISO-639), promotions: map{banners: map{id: str, type: str, page: [str], text: str}}, version: int}, meta: map}\n@example_request {\"customer_id\":0,\"line_items\":[{\"quantity\":2,\"product_id\":126,\"list_price\":5,\"name\":\"calendar\"}],\"channel_id\":1,\"currency\":{\"code\":\"USD\"},\"locale\":\"en-US\"}\n\n@endpoint POST /carts/{cartId}/items\n@desc Add Cart Line Items\n@optional {include: [str] # * `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., line_items: any, gift_certificates: [map{name!: str, theme!: str, amount!: num, quantity!: int, sender!: map, recipient!: map, message: str}], custom_items: [map{sku: str, name: str, quantity: num, list_price: num, image_url: str(uri)}], version: int # 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.}\n@returns(201) {data: map{id: str(UUID), customer_id: int, channel_id: int, email: str, currency: map{code: str(ISO-4217)}, tax_included: bool, base_amount: num, discount_amount: num, manual_discount_amount: num, cart_amount: num, coupons: [map], discounts: [map], line_items: map{physical_items: [any], digital_items: [any], gift_certificates: [map], custom_items: [map]}, created_time: str(ISO-8601), updated_time: str(ISO-8601), locale: str(ISO-639), promotions: map{banners: map{id: str, type: str, page: [str], text: str}}, version: int}, meta: map}\n@example_request {\"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\",\"amount\":50,\"quantity\":1,\"sender\":{\"name\":\"Jane Does\",\"email\":\"janedoe@example.com\"},\"recipient\":{\"name\":\"Jane Does\",\"email\":\"janedoe@example.com\"},\"message\":\"Happy Birthday Jane!\"}],\"version\":1}\n\n@endpoint POST /carts/{cartId}/redirect_urls\n@desc Create Cart Redirect URL\n@optional {query_params: map{key: str, value: str}}\n@returns(201) {data: map{cart_url: str(url), checkout_url: str(Url), embedded_checkout_url: str(url)}, meta: map}\n@example_request {\"query_params\":{\"key_1\":\"value_1\",\"key_2\":\"value_2\"}}\n\n@endpoint PUT /carts/{cartId}/items/{itemId}\n@desc Update Cart Line Item\n@required {Content-Type: str=application/json}\n@optional {include: [str] # * `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., line_item: any, gift_certificates: [map{name!: str, theme!: str, amount!: num, quantity!: int, sender!: map, recipient!: map, message: str}], custom_items: [map{sku: str, name: str, quantity: num, list_price: num, image_url: str(uri)}], version: int # 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.}\n@returns(200) {data: map{id: str(UUID), customer_id: int, channel_id: int, email: str, currency: map{code: str(ISO-4217)}, tax_included: bool, base_amount: num, discount_amount: num, manual_discount_amount: num, cart_amount: num, coupons: [map], discounts: [map], line_items: map{physical_items: [any], digital_items: [any], gift_certificates: [map], custom_items: [map]}, created_time: str(ISO-8601), updated_time: str(ISO-8601), locale: str(ISO-639), promotions: map{banners: map{id: str, type: str, page: [str], text: str}}, version: int}, meta: map}\n@errors {409: Cart conflict}\n\n@endpoint DELETE /carts/{cartId}/items/{itemId}\n@desc Delete Cart Line Item\n@optional {include: [str] # * `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., version: int # 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.}\n@returns(200) {id: str(UUID), customer_id: int, channel_id: int, email: str, currency: map{code: str(ISO-4217)}, tax_included: bool, base_amount: num, discount_amount: num, manual_discount_amount: num, cart_amount: num, coupons: [map], discounts: [map], line_items: map{physical_items: [any], digital_items: [any], gift_certificates: [map], custom_items: [map]}, created_time: str(ISO-8601), updated_time: str(ISO-8601), locale: str(ISO-639), promotions: map{banners: map{id: str, type: str, page: [str], text: str}}, version: int} # 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.\n@returns(204) If the action’s result is an empty cart, the cart is automatically deleted.\n@errors {409: Cart conflict}\n\n@endpoint GET /carts/{cartId}\n@desc Get a Cart\n@optional {include: [str] # * `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.}\n@returns(200) {data: map{id: str(UUID), customer_id: int, channel_id: int, email: str, currency: map{code: str(ISO-4217)}, tax_included: bool, base_amount: num, discount_amount: num, manual_discount_amount: num, cart_amount: num, coupons: [map], discounts: [map], line_items: map{physical_items: [any], digital_items: [any], gift_certificates: [map], custom_items: [map]}, created_time: str(ISO-8601), updated_time: str(ISO-8601), locale: str(ISO-639), promotions: map{banners: map{id: str, type: str, page: [str], text: str}}, version: int}, meta: map}\n@errors {404: Cart not found.}\n\n@endpoint PUT /carts/{cartId}\n@desc Update Customer ID\n@required {Content-Type: str=application/json}\n@optional {include: [str] # * `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., customer_id: int, version: int # 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.}\n@returns(201) {data: map{id: str(UUID), customer_id: int, channel_id: int, email: str, currency: map{code: str(ISO-4217)}, tax_included: bool, base_amount: num, discount_amount: num, manual_discount_amount: num, cart_amount: num, coupons: [map], discounts: [map], line_items: map{physical_items: [any], digital_items: [any], gift_certificates: [map], custom_items: [map]}, created_time: str(ISO-8601), updated_time: str(ISO-8601), locale: str(ISO-639), promotions: map{banners: map{id: str, type: str, page: [str], text: str}}, version: int}, meta: map}\n@errors {409: Cart conflict}\n@example_request {\"customer_id\":5,\"version\":1}\n\n@endpoint DELETE /carts/{cartId}\n@desc Delete a Cart\n@returns(204)\n\n@endpoint GET /carts/settings\n@desc Get Global Cart Settings\n@returns(200) {data: map{allow_purchasing: bool}, meta: map} # OK\n@errors {401: Unauthorized}\n\n@endpoint PUT /carts/settings\n@desc Update Global Cart Settings\n@required {Content-Type: str=application/json}\n@returns(200) {data: map{allow_purchasing: bool}, meta: map} # OK\n@errors {400: Bad Request. Input is invalid., 401: Unauthorized, 422: Unprocessable entity}\n\n@endpoint GET /carts/settings/channels/{channel_id}\n@desc Get Channel Cart Settings\n@returns(200) {data: map{allow_purchasing: bool?}, meta: map} # OK\n@errors {401: Unauthorized}\n\n@endpoint PUT /carts/settings/channels/{channel_id}\n@desc Update Channel Cart Settings\n@required {Content-Type: str=application/json}\n@returns(200) {data: map{allow_purchasing: bool?}, meta: map} # OK\n@errors {400: Bad Request. Input is invalid., 401: Unauthorized, 422: Unprocessable entity}\n\n@endpoint GET /carts/{cart_id}/metafields\n@desc Get Cart Metafields\n@optional {page: int # Specifies the page number in a limited (paginated) list of products., limit: int # Controls the number of items per page in a limited (paginated) list of products., key: str # Filter based on a metafieldʼs key., namespace: str # Filter based on a metafieldʼs namespaces., direction: str(asc/desc) # Sort direction. Acceptable values are: `asc`, `desc`., before: str # A cursor indicating where to start retrieving the previous page of results. Use this parameter to paginate backward. Not required for the initial request. For subsequent requests, use the end_cursor value returned in meta.cursor_pagination from the previous response. Works with limit, direction, and other supported query parameters. When specified, offset-based pagination (page) is ignored. Cannot be used in combination with the after parameter., after: str # A cursor indicating where to start retrieving the next page of results. Use this parameter to paginate forward. Not required for the initial request. For subsequent requests, use the start_cursor value returned in meta.cursor_pagination from the previous response. Works with limit, direction, and other supported query parameters. When specified, offset-based pagination (page) is ignored. Cannot be used in combination with the before parameter.}\n@returns(200) {data: any} # An array of metafields and metadata.\n\n@endpoint POST /carts/{cart_id}/metafields\n@desc Create a Cart Metafield\n@required {Content-Type: str=application/json, permission_set: str(app_only/read/write/read_and_sf_access/write_and_sf_access) # Determines the visibility and writeability of the field by other API consumers.  | Value | Description | | :--- | :--- | | `app_only` | Private to the app that owns the field. | | `read` | Visible to other API consumers. | | `write` | Open for reading and writing by other API consumers. | | `read_and_sf_access` | Visible to other API consumers, including on the storefront. | | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. |, namespace: str # Namespace for the metafield, for organizational purposes., key: str # The name of the field, for example: `location_id`, `color`., value: str # The value of the field, for example: `1`, `blue`.}\n@optional {description: str # Description for the metafields.}\n@returns(200) {data: any, meta: map} # A `Metafield` object.\n@errors {400: Bad Request. Input is invalid., 409: The `Metafield` conflicts with another `Metafield`. This can result from duplicate unique key combinations of the appʼs client id, namespace, key, resource_type, and resource_id., 422: The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.}\n@example_request {\"permission_set\":\"app_only\",\"namespace\":\"Sales Department\",\"key\":\"Staff Name\",\"value\":\"Sam\",\"description\":\"Name of staff member\"}\n\n@endpoint GET /carts/{cart_id}/metafields/{metafield_id}\n@desc Get a Cart Metafield\n@optional {page: int # Specifies the page number in a limited (paginated) list of products., limit: int # Controls the number of items per page in a limited (paginated) list of products., key: str # Filter based on a metafieldʼs key., namespace: str # Filter based on a metafieldʼs namespaces., direction: str(asc/desc) # Sort direction. Acceptable values are: `asc`, `desc`.}\n@returns(200) {data: any} # A `Metafield` object.\n@errors {404: Not found (A metafield was not found with this query).}\n\n@endpoint PUT /carts/{cart_id}/metafields/{metafield_id}\n@desc Update a Cart Metafield\n@required {Content-Type: str=application/json, permission_set: str(app_only/read/write/read_and_sf_access/write_and_sf_access) # Determines the visibility and writeability of the field by other API consumers.  | Value | Description | | :--- | :--- | | `app_only` | Private to the app that owns the field. | | `read` | Visible to other API consumers. | | `write` | Open for reading and writing by other API consumers. | | `read_and_sf_access` | Visible to other API consumers, including on the storefront. | | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. |, namespace: str # Namespace for the metafield, for organizational purposes., key: str # The name of the field, for example: `location_id`, `color`., value: str # The value of the field, for example: `1`, `blue`.}\n@optional {description: str # Description for the metafields.}\n@returns(200) {data: any, meta: map} # A `Metafield` and metadata.\n@errors {400: Bad Request. Metafield is invalid., 422: Response object for metafields creation with partial success.}\n\n@endpoint DELETE /carts/{cart_id}/metafields/{metafield_id}\n@desc Delete a Metafield\n@returns(204) An empty response.\n@errors {404: Not found (A metafield was not found with this query)}\n\n@endpoint GET /carts/metafields\n@desc Get All Cart Metafields\n@optional {page: int # Specifies the page number in a limited (paginated) list of products., limit: int # Controls the number of items per page in a limited (paginated) list of products., key: str # Filter based on a metafieldʼs key., key:in: [str] # Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter., namespace: str # Filter based on a metafieldʼs namespaces., namespace:in: [str] # Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter, direction: str(asc/desc) # Sort direction. Acceptable values are: `asc`, `desc`., include_fields: [str] # Fields to include, in a comma-separated list. The ID and the specified fields will be returned., date_modified:min: str # 'Query parameter that lets you filter by the minimum date modified created, for example, `2024-05-14T09:34:00` or `2024-05-14`. Returns metafields modified after this date.', date_modified:max: str # 'Query parameter that lets you filter by the maximum date modified created, for example, `2024-05-14T09:34:00` or `2024-05-14`. Returns metafields modified before this date.', date_created:min: str # 'Query parameter that lets you filter by the minimum date created, for example, `2024-05-14T09:34:00` or `2024-05-14`. Returns metafields created after this date.', date_created:max: str # 'Query parameter that lets you filter by the maximum date created, for example, `2024-05-14T09:34:00` or `2024-05-14`. Returns metafields created before this date.', before: str # A cursor indicating where to start retrieving the previous page of results. Use this parameter to paginate backward. Not required for the initial request. For subsequent requests, use the end_cursor value returned in meta.cursor_pagination from the previous response. Works with limit, direction, and other supported query parameters. When specified, offset-based pagination (page) is ignored. Cannot be used in combination with the after parameter., after: str # A cursor indicating where to start retrieving the next page of results. Use this parameter to paginate forward. Not required for the initial request. For subsequent requests, use the start_cursor value returned in meta.cursor_pagination from the previous response. Works with limit, direction, and other supported query parameters. When specified, offset-based pagination (page) is ignored. Cannot be used in combination with the before parameter.}\n@returns(200) {data: [any], meta: map{pagination: map{total: int, count: int, per_page: int, current_page: int, total_pages: int, links: map{previous: str, current: str, next: str}}, cursor_pagination: map{count: int, per_page: int, start_cursor: str, end_cursor: str, links: map{previous: str, current: str, next: str}}}} # List of `Metafield` objects.\n\n@endpoint POST /carts/metafields\n@desc Create multiple Metafields\n@returns(200) {data: [any], errors: [any], meta: map{total: int, success: int, failed: int}} # List of created `Metafield` objects.\n@errors {400: Bad Request. Input is invalid., 422: Response object for metafields creation with partial success.}\n\n@endpoint PUT /carts/metafields\n@desc Update multiple Metafields\n@returns(200) {data: [any], errors: [any], meta: map{total: int, success: int, failed: int}} # List of updated `Metafield` objects.\n@errors {400: Bad Request. Input is invalid., 422: Response object for metafields creation with partial success.}\n\n@endpoint DELETE /carts/metafields\n@desc Delete multiple Metafields\n@returns(200) {data: [int], errors: [any], meta: map{total: int, success: int, failed: int}} # Response object for metafields deletion with success.\n@errors {400: Bad Request. Input is invalid., 422: Response object for metafields deletion with partial success.}\n\n@end\n"}}