@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Carts
@base https://api.bigcommerce.com/stores/{store_hash}/v3
@auth ApiKey X-Auth-Token in header
@endpoints 21
@hint download_for_search
@toc carts(21)

@endpoint POST /carts
@desc Create a Cart
@required {Content-Type: str=application/json}
@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.}
@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}
@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"}

@endpoint POST /carts/{cartId}/items
@desc Add Cart Line Items
@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.}
@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}
@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}

@endpoint POST /carts/{cartId}/redirect_urls
@desc Create Cart Redirect URL
@optional {query_params: map{key: str, value: str}}
@returns(201) {data: map{cart_url: str(url), checkout_url: str(Url), embedded_checkout_url: str(url)}, meta: map}
@example_request {"query_params":{"key_1":"value_1","key_2":"value_2"}}

@endpoint PUT /carts/{cartId}/items/{itemId}
@desc Update Cart Line Item
@required {Content-Type: str=application/json}
@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.}
@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}
@errors {409: Cart conflict}

@endpoint DELETE /carts/{cartId}/items/{itemId}
@desc Delete Cart Line Item
@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.}
@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.
@returns(204) If the action’s result is an empty cart, the cart is automatically deleted.
@errors {409: Cart conflict}

@endpoint GET /carts/{cartId}
@desc Get a Cart
@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.}
@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}
@errors {404: Cart not found.}

@endpoint PUT /carts/{cartId}
@desc Update Customer ID
@required {Content-Type: str=application/json}
@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.}
@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}
@errors {409: Cart conflict}
@example_request {"customer_id":5,"version":1}

@endpoint DELETE /carts/{cartId}
@desc Delete a Cart
@returns(204)

@endpoint GET /carts/settings
@desc Get Global Cart Settings
@returns(200) {data: map{allow_purchasing: bool}, meta: map} # OK
@errors {401: Unauthorized}

@endpoint PUT /carts/settings
@desc Update Global Cart Settings
@required {Content-Type: str=application/json}
@returns(200) {data: map{allow_purchasing: bool}, meta: map} # OK
@errors {400: Bad Request. Input is invalid., 401: Unauthorized, 422: Unprocessable entity}

@endpoint GET /carts/settings/channels/{channel_id}
@desc Get Channel Cart Settings
@returns(200) {data: map{allow_purchasing: bool?}, meta: map} # OK
@errors {401: Unauthorized}

@endpoint PUT /carts/settings/channels/{channel_id}
@desc Update Channel Cart Settings
@required {Content-Type: str=application/json}
@returns(200) {data: map{allow_purchasing: bool?}, meta: map} # OK
@errors {400: Bad Request. Input is invalid., 401: Unauthorized, 422: Unprocessable entity}

@endpoint GET /carts/{cart_id}/metafields
@desc Get Cart Metafields
@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.}
@returns(200) {data: any} # An array of metafields and metadata.

@endpoint POST /carts/{cart_id}/metafields
@desc Create a Cart Metafield
@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`.}
@optional {description: str # Description for the metafields.}
@returns(200) {data: any, meta: map} # A `Metafield` object.
@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.}
@example_request {"permission_set":"app_only","namespace":"Sales Department","key":"Staff Name","value":"Sam","description":"Name of staff member"}

@endpoint GET /carts/{cart_id}/metafields/{metafield_id}
@desc Get a Cart Metafield
@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`.}
@returns(200) {data: any} # A `Metafield` object.
@errors {404: Not found (A metafield was not found with this query).}

@endpoint PUT /carts/{cart_id}/metafields/{metafield_id}
@desc Update a Cart Metafield
@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`.}
@optional {description: str # Description for the metafields.}
@returns(200) {data: any, meta: map} # A `Metafield` and metadata.
@errors {400: Bad Request. Metafield is invalid., 422: Response object for metafields creation with partial success.}

@endpoint DELETE /carts/{cart_id}/metafields/{metafield_id}
@desc Delete a Metafield
@returns(204) An empty response.
@errors {404: Not found (A metafield was not found with this query)}

@endpoint GET /carts/metafields
@desc Get All Cart Metafields
@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.}
@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.

@endpoint POST /carts/metafields
@desc Create multiple Metafields
@returns(200) {data: [any], errors: [any], meta: map{total: int, success: int, failed: int}} # List of created `Metafield` objects.
@errors {400: Bad Request. Input is invalid., 422: Response object for metafields creation with partial success.}

@endpoint PUT /carts/metafields
@desc Update multiple Metafields
@returns(200) {data: [any], errors: [any], meta: map{total: int, success: int, failed: int}} # List of updated `Metafield` objects.
@errors {400: Bad Request. Input is invalid., 422: Response object for metafields creation with partial success.}

@endpoint DELETE /carts/metafields
@desc Delete multiple Metafields
@returns(200) {data: [int], errors: [any], meta: map{total: int, success: int, failed: int}} # Response object for metafields deletion with success.
@errors {400: Bad Request. Input is invalid., 422: Response object for metafields deletion with partial success.}

@end