diff --git a/reference/carts.v3.yml b/reference/carts.v3.yml index 9348ddcb3..160fab6b2 100644 --- a/reference/carts.v3.yml +++ b/reference/carts.v3.yml @@ -26,6 +26,7 @@ tags: - name: Redirects - name: Settings - name: Metafields + - name: Batch metafields paths: '/carts': parameters: @@ -177,76 +178,41 @@ paths: currency: code: usd locale: en-US - description: |- + 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 - } - ] - } - ] - } + 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 @@ -534,7 +500,7 @@ paths: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/cartId' get: - description: Returns a store's *Cart*. + description: Returns a storeʼs *Cart*. parameters: - name: include in: query @@ -561,7 +527,7 @@ paths: operationId: getCart put: description: |- - Updates a *Cart's* `customer_id`. + Updates a *Cartʼs* `customer_id`. **Notes** @@ -779,7 +745,7 @@ paths: tags: - Metafields description: Get all cart metafields. - operationId: getAllCartMetafields + operationId: getCartMetafields parameters: - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/LimitParam' @@ -796,7 +762,7 @@ paths: $ref: '#/components/schemas/MetafieldResponse' '409': description: | - The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. + 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. content: application/json: schema: @@ -823,15 +789,13 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/MetafieldPost' + $ref: '#/components/schemas/MetafieldBase_Post' example: - { - "permission_set": app_only, - "namespace": Sales Department, - "key": Staff Name, - "value": Sam, - "description": Name of staff member - } + permission_set: app_only + namespace: Sales Department + key: Staff Name + value: Sam + description: Name of staff member description: '' required: true responses: @@ -885,7 +849,7 @@ paths: $ref: '#/components/schemas/MetafieldResponse' '409': description: | - The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. + 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. content: application/json: schema: @@ -918,7 +882,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/MetafieldPost' + $ref: '#/components/schemas/MetafieldBase_Post' examples: {} description: | A `Metafield` object. @@ -965,6 +929,142 @@ paths: in: path required: true description: The unique ID of the subject `Metafield`. + '/carts/metafields': + get: + summary: Get All Metafields + tags: + - Batch metafields + description: Get all cart metafields. + operationId: getCartsMetafields + responses: + '200': + description: | + List of `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_Batch' + '500': + description: Internal Server Error + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/MetafieldKeyParam' + - $ref: '#/components/parameters/MetafieldKeyInParam' + - $ref: '#/components/parameters/MetafieldNamespaceParam' + - $ref: '#/components/parameters/MetafieldNamespaceInParam' + - $ref: '#/components/parameters/DirectionParam' + post: + summary: Create multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: createCartsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + resource_id: + type: string + example: "42" + description: | + The ID for the cart with which the metafield is associated. + required: + - resource_id + description: '' + responses: + '200': + description: | + List of created `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_Batch_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + put: + summary: Update multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: updateCartsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + id: + type: string + example: "42" + description: | + The ID of metafield to update. + required: + - id + description: '' + responses: + '200': + description: | + List of updated `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_Batch_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + delete: + summary: Delete All Metafields + tags: + - Batch metafields + description: Delete all cart metafields. + operationId: deleteCartsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + type: integer + description: List of metafield `id`s. + responses: + '200': + description: | + Response object for metafields deletion with success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess' + '422': + description: | + Response object for metafields deletion with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE' components: schemas: CartUpdateRequest: @@ -2126,7 +2226,7 @@ components: description: SKU of the variant. name: type: string - description: The item's product name. + description: The itemʼs product name. example: T-Shirt url: description: The product URL. @@ -2373,7 +2473,7 @@ components: type: object title: Item Custom description: |- - Add a custom item to the shopper's cart. + 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. @@ -2397,7 +2497,7 @@ components: type: object title: Item Custom description: |- - Add a custom item to the shopper's cart. + 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. @@ -3013,13 +3113,18 @@ components: date_created: type: string format: date-time - description: Date and time of the metafield's creation. + description: Date and time of the metafieldʼs creation. example: '2022-06-16T18:39:00+00:00' date_modified: type: string format: date-time description: Date and time when the metafield was last updated. example: '2022-06-16T18:39:00+00:00' + owner_client_id: + type: string + description: Client ID for the metafieldʼs creator. + example: asdfasdfasdfasdfasdfasdfasdf + readOnly: true x-internal: false MetafieldBase: type: object @@ -3036,8 +3141,8 @@ components: | `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 storefront. | - | `write_and_sf_access` | Open for reading and writing by other API consumers, including on storefront. | + | `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. | enum: - app_only - read @@ -3091,12 +3196,6 @@ components: readOnly: true required: - permission_set - MetafieldPost: - description: | - The model for a POST to create metafield. - allOf: - - $ref: '#/components/schemas/MetafieldBase_Post' - x-internal: false MetafieldBase_Post: type: object description: | @@ -3112,8 +3211,8 @@ components: | `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 storefront. | - | `write_and_sf_access` | Open for reading and writing by other API consumers, including on storefront. | + | `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. | enum: - app_only - read @@ -3163,13 +3262,167 @@ components: meta: $ref: '#/components/schemas/CollectionMeta' x-internal: false + MetaFieldCollectionResponse_Batch: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + meta: + $ref: '#/components/schemas/CollectionMeta' + MetaFieldCollectionResponse_Batch_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/CollectionMeta' + MetaFieldCollectionDeleteResponseSuccess: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + - 124 + - 125 + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/WriteCollectionSuccessMeta' + x-internal: false + MetaFieldCollectionResponsePartialSuccess_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + MetaFieldCollectionResponsePartialSuccess_DELETE: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + x-internal: false + Error: + type: object + description: | + Error response payload for the BigCommerce API. + properties: + status: + type: integer + description: | + The HTTP status code for the error. + example: 422 + title: + type: string + description: | + The error title. + example: Bulk operation has failed + type: + type: string + description: | + The error type. + example: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes + errors: + $ref: '#/components/schemas/ErrorDetail' + ErrorDetail: + type: object + description: | + Error detail response payload for the BigCommerce API. + example: + "1": "Unauthorized to delete" + "2": "Metafield does not exist" + WriteCollectionSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 3 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 0 + title: Collection Meta + x-internal: false + WriteCollectionPartialSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + title: Collection Meta + x-internal: false CollectionMeta: type: object - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. properties: pagination: type: object - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. title: Pagination properties: total: @@ -3330,17 +3583,39 @@ components: MetafieldKeyParam: name: key in: query - description: Filter based on a metafield's key. + description: Filter based on a metafieldʼs key. required: false schema: type: string + MetafieldKeyInParam: + name: key:in + in: query + description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string MetafieldNamespaceParam: name: namespace in: query - description: Filter based on a metafield's key. + description: Filter based on a metafieldʼs namespaces. required: false schema: type: string + MetafieldNamespaceInParam: + name: namespace:in + in: query + description: Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string LimitParam: name: limit description: | diff --git a/reference/catalog/brands_catalog.v3.yml b/reference/catalog/brands_catalog.v3.yml index 4d6035757..6ba41dc7d 100644 --- a/reference/catalog/brands_catalog.v3.yml +++ b/reference/catalog/brands_catalog.v3.yml @@ -4,7 +4,7 @@ info: description: |- > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). - Our Catalog Brands endpoints let you [create individual brands](/docs/rest-catalog/brands#create-a-brand) and [modify the brands](/docs/rest-catalog/brands#update-a-brand) associated with a store's products, along with [deleting brands](/docs/rest-catalog/brands#delete-a-brand). + Our Catalog Brands endpoints let you [create individual brands](/docs/rest-catalog/brands#create-a-brand) and [modify the brands](/docs/rest-catalog/brands#update-a-brand) associated with a storeʼs products, along with [deleting brands](/docs/rest-catalog/brands#delete-a-brand). Brand images have their own dedicated [create a brand image](/docs/rest-catalog/brands/images#create-a-brand-image) and [delete a brand image](/docs/rest-catalog/brands/images#delete-a-brand-image) endpoints. @@ -44,6 +44,7 @@ tags: - name: Brands - name: Images - name: Metafields + - name: Batch metafields paths: '/catalog/brands': get: @@ -633,7 +634,7 @@ paths: - Brands summary: Get a Brand description: Returns a single *Brand*. Optional filter parameters can be passed in. - operationId: getBrandById + operationId: getBrand parameters: - name: include_fields in: query @@ -1065,12 +1066,12 @@ paths: - name: key in: query description: | - Filter based on a metafield's key. + Filter based on a metafieldʼs key. schema: type: string - name: namespace in: query - description: Filter based on a metafield's namespace. + description: Filter based on a metafieldʼs namespace. schema: type: string - name: include_fields @@ -1237,7 +1238,7 @@ paths: meta: {} '409': description: | - The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique key combination of the app's client id, namespace, key, resource_type, and resource_id. + The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique key combination of the appʼs client id, namespace, key, resource_type, and resource_id. content: application/json: schema: @@ -1588,6 +1589,142 @@ paths: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/BrandIdParam' + '/catalog/brands/metafields': + get: + summary: Get All Metafields + tags: + - Batch metafields + description: Get all brand metafields. + operationId: getBrandsMetafields + responses: + '200': + description: | + List of `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse' + '500': + description: Internal Server Error + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/MetafieldKeyParam' + - $ref: '#/components/parameters/MetafieldKeyInParam' + - $ref: '#/components/parameters/MetafieldNamespaceParam' + - $ref: '#/components/parameters/MetafieldNamespaceInParam' + - $ref: '#/components/parameters/DirectionParam' + post: + summary: Create multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: createBrandsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + resource_id: + type: integer + example: 42 + description: | + The ID for the brand with which the metafield is associated. + required: + - resource_id + description: '' + responses: + '200': + description: | + List of created `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + put: + summary: Update multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: updateBrandsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Put' + - type: object + properties: + id: + type: integer + example: 42 + description: | + The ID of metafield to update. + required: + - id + description: '' + responses: + '200': + description: | + List of updated `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + delete: + summary: Delete All Metafields + tags: + - Batch metafields + description: Delete all brand metafields. + operationId: deleteBrandsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + type: integer + description: List of metafield IDs. + responses: + '200': + description: | + Response object for metafields deletion with success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess' + '422': + description: | + Response object for metafields deletion with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE' components: schemas: brand_Full: @@ -1744,7 +1881,7 @@ components: properties: pagination: $ref: '#/components/schemas/pagination_Full' - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. x-internal: false pagination_Full: title: pagination_Full @@ -1793,7 +1930,7 @@ components: Link to the next page returned in the response. description: | Pagination links for the previous and next parts of the whole collection. - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. x-internal: false metaEmpty_Full: type: object @@ -1857,7 +1994,7 @@ components: date_created: type: string description: | - Date and time of the metafield's creation. Read-Only. + Date and time of the metafieldʼs creation. Read-Only. readOnly: true format: date-time example: '2018-05-07T20:14:17+00:00' @@ -1869,13 +2006,444 @@ components: format: date-time example: '2018-05-07T20:14:17+00:00' x-internal: false - responses: - General207Status: - description: 'Multi-status. Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occured, such as when a `POST` or `PUT` request is successful, but saving the URL or inventory data has failed.' - content: - application/json: - schema: - $ref: '#/components/schemas/error_Base' + Metafield: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + example: order + minLength: 0 + maxLength: 255 + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + enum: + - brand + - product + - variant + - category + - cart + - channel + - location + - order + - customer + example: cart + resource_id: + type: integer + description: | + The unique identifier for the resource with which the metafield is associated. + example: 424242 + readOnly: true + id: + type: integer + description: The unique identifier for the metafield. + date_created: + type: string + format: date-time + description: Date and time of the metafieldʼs creation. + example: '2022-06-16T18:39:00+00:00' + date_modified: + type: string + format: date-time + description: Date and time when the metafield was last updated. + example: '2022-06-16T18:39:00+00:00' + owner_client_id: + type: string + description: Client ID for the metafieldʼs creator. + example: asdfasdfasdfasdfasdfasdfasdf + readOnly: true + required: + - namespace + - key + - value + - permission_set + - resource_type + - resource_id + - description + - id + - date_created + - date_modified + MetaFieldCollectionResponse: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + meta: + $ref: '#/components/schemas/CollectionMeta' + x-internal: false + MetaFieldCollectionResponse_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/CollectionMeta' + MetaFieldCollectionResponsePartialSuccess_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + MetaFieldCollectionResponsePartialSuccess_DELETE: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + x-internal: false + MetaFieldCollectionDeleteResponseSuccess: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + - 124 + - 125 + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/WriteCollectionSuccessMeta' + x-internal: false + WriteCollectionPartialSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + title: Collection Meta + x-internal: false + WriteCollectionSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 3 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 0 + title: Collection Meta + x-internal: false + Total: + type: integer + description: | + Total number of items in the result set. + example: 3 + Error: + type: object + description: | + Error response payload for the BigCommerce API. + properties: + status: + type: integer + description: | + The HTTP status code for the error. + example: 422 + title: + type: string + description: | + The error title. + example: Bulk operation has failed + type: + type: string + description: | + The error type. + example: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes + errors: + $ref: '#/components/schemas/ErrorDetail' + ErrorDetail: + type: object + description: | + Error detail response payload for the BigCommerce API. + example: + "1": "Unauthorized to delete" + "2": "Metafield does not exist" + CollectionMeta: + type: object + description: Data about the response, including pagination and collection totals. + properties: + pagination: + type: object + description: Data about the response, including pagination and collection totals. + title: Pagination + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + description: | + Pagination links for the previous and next parts of the whole collection. + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + additionalProperties: true + title: Collection Meta + x-internal: false + MetafieldBase_Post: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member + required: + - permission_set + - namespace + - key + - value + MetafieldPost: + description: | + The model for a POST to create metafield. + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + resource_id: + type: integer + example: 42 + description: | + The ID for the resource with which the metafield is associated. + required: + - resource_id + x-internal: false + MetafieldBase_Put: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member parameters: BrandIdParam: name: brand_id @@ -1909,6 +2477,76 @@ components: schema: type: string default: 'application/json' + PageParam: + name: page + description: | + Specifies the page number in a limited (paginated) list of products. + required: false + in: query + schema: + type: integer + MetafieldKeyParam: + name: key + in: query + description: Filter based on a metafieldʼs key. + required: false + schema: + type: string + MetafieldKeyInParam: + name: key:in + in: query + description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + MetafieldNamespaceParam: + name: namespace + in: query + description: Filter based on a metafieldʼs namespaces. + required: false + schema: + type: string + MetafieldNamespaceInParam: + name: namespace:in + in: query + description: Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + LimitParam: + name: limit + description: | + Controls the number of items per page in a limited (paginated) list of products. + required: false + in: query + schema: + type: integer + DirectionParam: + name: direction + description: | + Sort direction. Acceptable values are: `asc`, `desc`. + required: false + in: query + schema: + type: string + enum: + - asc + - desc + responses: + General207Status: + description: Multi-status. Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred, such as when a `POST` or `PUT` request is successful, but saving the URL or inventory data has failed. + content: + application/json: + schema: + $ref: '#/components/schemas/error_Base' securitySchemes: X-Auth-Token: name: X-Auth-Token diff --git a/reference/catalog/categories_catalog.v3.yml b/reference/catalog/categories_catalog.v3.yml index c66f0585a..e2c2387b2 100644 --- a/reference/catalog/categories_catalog.v3.yml +++ b/reference/catalog/categories_catalog.v3.yml @@ -46,6 +46,7 @@ servers: security: - X-Auth-Token: [] tags: + - name: Batch metafields - name: Metafields - name: Images - name: Sort Order @@ -389,7 +390,7 @@ paths: parent_id: type: integer description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + The unique numeric ID of the categoryʼs parent. This field controls where the category sits in the tree of categories that organize the catalog. Required in a POST if creating a child category. example: 2 x-required: @@ -399,7 +400,7 @@ paths: minLength: 1 type: string description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. + The name displayed for the category. Name is unique with respect to the categoryʼs siblings. Required in a POST. example: Bath x-required: @@ -437,7 +438,7 @@ paths: meta_keywords: type: array description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + Custom meta keywords for the category page. If not defined, the storeʼs default keywords will be used. Must post as an array like: ["awesome","sauce"]. items: type: string meta_description: @@ -445,7 +446,7 @@ paths: minLength: 0 type: string description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. + Custom meta description for the category page. If not defined, the storeʼs default meta description will be used. layout_file: maxLength: 500 minLength: 0 @@ -831,7 +832,7 @@ paths: parent_id: type: integer description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + The unique numeric ID of the categoryʼs parent. This field controls where the category sits in the tree of categories that organize the catalog. Required in a POST if creating a child category. example: 2 x-required: @@ -841,7 +842,7 @@ paths: minLength: 1 type: string description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. + The name displayed for the category. Name is unique with respect to the categoryʼs siblings. Required in a POST. example: Bath x-required: @@ -879,7 +880,7 @@ paths: meta_keywords: type: array description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + Custom meta keywords for the category page. If not defined, the storeʼs default keywords will be used. Must post as an array like: ["awesome","sauce"]. items: type: string meta_description: @@ -887,7 +888,7 @@ paths: minLength: 0 type: string description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. + Custom meta description for the category page. If not defined, the storeʼs default meta description will be used. layout_file: maxLength: 500 minLength: 0 @@ -969,7 +970,7 @@ paths: parent_id: type: integer description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + The unique numeric ID of the categoryʼs parent. This field controls where the category sits in the tree of categories that organize the catalog. Required in a POST if creating a child category. example: 2 x-required: @@ -979,7 +980,7 @@ paths: minLength: 1 type: string description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. + The name displayed for the category. Name is unique with respect to the categoryʼs siblings. Required in a POST. example: Bath x-required: @@ -1017,7 +1018,7 @@ paths: meta_keywords: type: array description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + Custom meta keywords for the category page. If not defined, the storeʼs default keywords will be used. Must post as an array like: ["awesome","sauce"]. items: type: string meta_description: @@ -1025,7 +1026,7 @@ paths: minLength: 0 type: string description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. + Custom meta description for the category page. If not defined, the storeʼs default meta description will be used. layout_file: maxLength: 500 minLength: 0 @@ -1255,12 +1256,12 @@ paths: - name: key in: query description: | - Filter based on a metafield's key. + Filter based on a metafieldʼs key. schema: type: string - name: namespace in: query - description: Filter based on a metafield's namespace. + description: Filter based on a metafieldʼs namespace. schema: type: string - name: include_fields @@ -1394,7 +1395,7 @@ paths: meta: {} '409': description: | - The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate, unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. + The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate, unique key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. content: application/json: schema: @@ -1783,6 +1784,142 @@ paths: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/CategoryIdParam' + '/catalog/categories/metafields': + get: + summary: Get All Metafields + tags: + - Batch metafields + description: Get all category metafields. + operationId: getCategoriesMetafields + responses: + '200': + description: | + List of `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse' + '500': + description: Internal Server Error + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/MetafieldKeyParam' + - $ref: '#/components/parameters/MetafieldKeyInParam' + - $ref: '#/components/parameters/MetafieldNamespaceParam' + - $ref: '#/components/parameters/MetafieldNamespaceInParam' + - $ref: '#/components/parameters/DirectionParam' + post: + summary: Create multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: createCategoriesMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + resource_id: + type: integer + example: 42 + description: | + The ID for the category with which the metafield is associated. + required: + - resource_id + description: '' + responses: + '200': + description: | + List of created `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + put: + summary: Update multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: updateCategoriesMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Put' + - type: object + properties: + id: + type: integer + example: 42 + description: | + The ID of metafield to update. + required: + - id + description: '' + responses: + '200': + description: | + List of updated `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + delete: + summary: Delete All Metafields + tags: + - Batch metafields + description: Delete all category metafields. + operationId: deleteCategoriesMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + type: integer + description: List of metafield IDs. + responses: + '200': + description: | + Response object for metafields deletion with success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess' + '422': + description: | + Response object for metafields deletion with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE' components: schemas: category_Full: @@ -1800,7 +1937,7 @@ components: parent_id: type: integer description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + The unique numeric ID of the categoryʼs parent. This field controls where the category sits in the tree of categories that organize the catalog. Required in a POST if creating a child category. example: 2 x-required: @@ -1810,7 +1947,7 @@ components: minLength: 1 type: string description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. + The name displayed for the category. Name is unique with respect to the categoryʼs siblings. Required in a POST. example: Bath x-required: @@ -1848,7 +1985,7 @@ components: meta_keywords: type: array description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + Custom meta keywords for the category page. If not defined, the storeʼs default keywords will be used. Must post as an array like: ["awesome","sauce"]. items: type: string meta_description: @@ -1856,7 +1993,7 @@ components: minLength: 0 type: string description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. + Custom meta description for the category page. If not defined, the storeʼs default meta description will be used. layout_file: maxLength: 500 minLength: 0 @@ -1985,7 +2122,7 @@ components: properties: pagination: $ref: '#/components/schemas/pagination_Full' - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. x-internal: false pagination_Full: title: pagination_Full @@ -2034,7 +2171,7 @@ components: Link to the next page returned in the response. description: | Pagination links for the previous and next parts of the whole collection. - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. x-internal: false metaEmpty_Full: type: object @@ -2098,7 +2235,7 @@ components: date_created: type: string description: | - Date and time of the metafield's creation. Read-Only. + Date and time of the metafieldʼs creation. Read-Only. readOnly: true format: date-time example: '2018-05-07T20:14:17+00:00' @@ -2151,7 +2288,6 @@ components: properties: custom_url: $ref: '#/components/schemas/Url' - x-examples: {} Url: type: object properties: @@ -2188,7 +2324,7 @@ components: minLength: 1 type: string description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. + The name displayed for the category. Name is unique with respect to the categoryʼs siblings. Required in a POST. example: Bath description: @@ -2242,7 +2378,7 @@ components: meta_keywords: type: array description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + Custom meta keywords for the category page. If not defined, the storeʼs default keywords will be used. Must post as an array like: ["awesome","sauce"]. items: type: string layout_file: @@ -2283,7 +2419,7 @@ components: minLength: 0 type: string description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. + Custom meta description for the category page. If not defined, the storeʼs default meta description will be used. id: title: id type: object @@ -2301,9 +2437,442 @@ components: parent_id: type: integer description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + The unique numeric ID of the categoryʼs parent. This field controls where the category sits in the tree of categories that organize the catalog. Required in a POST if creating a child category. example: 2 + Metafield: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + example: order + minLength: 0 + maxLength: 255 + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + enum: + - brand + - product + - variant + - category + - cart + - channel + - location + - order + - customer + example: cart + resource_id: + type: integer + description: | + The unique identifier for the resource with which the metafield is associated. + example: 424242 + readOnly: true + id: + type: integer + description: The unique identifier for the metafield. + date_created: + type: string + format: date-time + description: Date and time of the metafieldʼs creation. + example: '2022-06-16T18:39:00+00:00' + date_modified: + type: string + format: date-time + description: Date and time when the metafield was last updated. + example: '2022-06-16T18:39:00+00:00' + owner_client_id: + type: string + description: Client ID for the metafieldʼs creator. + example: asdfasdfasdfasdfasdfasdfasdf + readOnly: true + required: + - namespace + - key + - value + - permission_set + - resource_type + - resource_id + - description + - id + - date_created + - date_modified + MetaFieldCollectionResponse: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + meta: + $ref: '#/components/schemas/CollectionMeta' + x-internal: false + MetaFieldCollectionResponse_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/CollectionMeta' + MetaFieldCollectionResponsePartialSuccess_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + MetaFieldCollectionResponsePartialSuccess_DELETE: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + x-internal: false + MetaFieldCollectionDeleteResponseSuccess: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + - 124 + - 125 + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/WriteCollectionSuccessMeta' + x-internal: false + WriteCollectionPartialSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + title: Collection Meta + x-internal: false + WriteCollectionSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 3 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 0 + title: Collection Meta + x-internal: false + Total: + type: integer + description: | + Total number of items in the result set. + example: 3 + Success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + Failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + Error: + type: object + description: | + Error response payload for the BigCommerce API. + properties: + status: + type: integer + description: | + The HTTP status code for the error. + example: 422 + title: + type: string + description: | + The error title. + example: Bulk operation has failed + type: + type: string + description: | + The error type. + example: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes + errors: + $ref: '#/components/schemas/ErrorDetail' + ErrorDetail: + type: object + description: | + Error detail response payload for the BigCommerce API. + example: + "1": "Unauthorized to delete" + "2": "Metafield does not exist" + CollectionMeta: + type: object + description: Data about the response, including pagination and collection totals. + properties: + pagination: + type: object + description: Data about the response, including pagination and collection totals. + title: Pagination + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + description: | + Pagination links for the previous and next parts of the whole collection. + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + additionalProperties: true + title: Collection Meta + x-internal: false + MetafieldBase_Post: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member + required: + - permission_set + - namespace + - key + - value + MetafieldBase_Put: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member responses: General207Status: description: 'Multi-status. Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred, such as when a `POST` or `PUT` request is successful, but saving the URL or inventory data has failed.' @@ -2344,6 +2913,69 @@ components: schema: type: string default: 'application/json' + PageParam: + name: page + description: | + Specifies the page number in a limited (paginated) list of products. + required: false + in: query + schema: + type: integer + MetafieldKeyParam: + name: key + in: query + description: Filter based on a metafieldʼs key. + required: false + schema: + type: string + MetafieldKeyInParam: + name: key:in + in: query + description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + MetafieldNamespaceParam: + name: namespace + in: query + description: Filter based on a metafieldʼs namespaces. + required: false + schema: + type: string + MetafieldNamespaceInParam: + name: namespace:in + in: query + description: Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + LimitParam: + name: limit + description: | + Controls the number of items per page in a limited (paginated) list of products. + required: false + in: query + schema: + type: integer + DirectionParam: + name: direction + description: | + Sort direction. Acceptable values are: `asc`, `desc`. + required: false + in: query + schema: + type: string + enum: + - asc + - desc securitySchemes: X-Auth-Token: name: X-Auth-Token diff --git a/reference/catalog/product-variants_catalog.v3.yml b/reference/catalog/product-variants_catalog.v3.yml index 7af56d9a6..28652f72f 100644 --- a/reference/catalog/product-variants_catalog.v3.yml +++ b/reference/catalog/product-variants_catalog.v3.yml @@ -47,6 +47,7 @@ servers: security: - X-Auth-Token: [] tags: + - name: Batch metafields - name: Product Variants - name: Variants (Batch) - name: Metafields @@ -566,7 +567,6 @@ paths: required: true schema: type: integer - - name: page in: query description: Specifies the page number in a limited (paginated) list of products. @@ -580,12 +580,12 @@ paths: - name: key in: query description: | - Filter based on a metafield's key. + Filter based on a metafieldʼs key. schema: type: string - name: namespace in: query - description: Filter based on a metafield's namespace. + description: Filter based on a metafieldʼs namespace. schema: type: string - name: include_fields @@ -695,7 +695,7 @@ paths: meta: {} '409': description: | - The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique-key combinations of the app's client id, namespace, key, resource_type, and resource_id. + The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique-key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. content: application/json: schema: @@ -1152,21 +1152,21 @@ paths: minimum: 0 type: number description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width. format: double x-nullable: true height: minimum: 0 type: number description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height. format: double x-nullable: true depth: minimum: 0 type: number description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth. format: double x-nullable: true is_free_shipping: @@ -1226,11 +1226,11 @@ paths: type: string sku_id: type: integer - description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. + description: Read-only reference to v2 APIʼs SKU ID. Null if it is a base variant. x-nullable: true option_values: type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. + description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant. items: title: Option Value Variant type: object @@ -1300,7 +1300,7 @@ paths: **Required Fields** To update an existing variant: - * id (variant id) + * id (variant ID) To create a new variant: * product_id @@ -1366,7 +1366,7 @@ paths: minimum: 0 type: number description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width. format: double x-nullable: true example: 5 @@ -1374,7 +1374,7 @@ paths: minimum: 0 type: number description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height. format: double x-nullable: true example: 5 @@ -1382,7 +1382,7 @@ paths: minimum: 0 type: number description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth. format: double x-nullable: true example: 5 @@ -1495,21 +1495,21 @@ paths: minimum: 0 type: number description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width. format: double x-nullable: true height: minimum: 0 type: number description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height. format: double x-nullable: true depth: minimum: 0 type: number description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth. format: double x-nullable: true is_free_shipping: @@ -1569,11 +1569,11 @@ paths: type: string sku_id: type: integer - description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. + description: Read-only reference to v2 APIʼs SKU ID. Null if it is a base variant. x-nullable: true option_values: type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. + description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant. items: title: Option Value Variant type: object @@ -1662,8 +1662,8 @@ paths: Link to the next page returned in the response. description: | Pagination links for the previous and next parts of the whole collection. - description: 'Data about the response, including pagination and collection totals.' - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. + description: Data about the response, including pagination and collection totals. '413': description: '' content: @@ -1717,6 +1717,142 @@ paths: x-codegen-request-body-name: body parameters: - $ref: '#/components/parameters/Accept' + '/catalog/variants/metafields': + get: + summary: Get All Metafields + tags: + - Batch metafields + description: Get all variant metafields. + operationId: getVariantsMetafields + responses: + '200': + description: | + List of `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse' + '500': + description: Internal Server Error + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/MetafieldKeyParam' + - $ref: '#/components/parameters/MetafieldKeyInParam' + - $ref: '#/components/parameters/MetafieldNamespaceParam' + - $ref: '#/components/parameters/MetafieldNamespaceInParam' + - $ref: '#/components/parameters/DirectionParam' + post: + summary: Create multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: createVariantsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + resource_id: + type: integer + example: 42 + description: | + The ID for the product variant with which the metafield is associated. + required: + - resource_id + description: '' + responses: + '200': + description: | + List of created `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + put: + summary: Update multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: updateVariantsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Put' + - type: object + properties: + id: + type: integer + example: 42 + description: | + The ID of metafield to update. + required: + - id + description: '' + responses: + '200': + description: | + List of updated `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + delete: + summary: Delete All Metafields + tags: + - Batch metafields + description: Delete all variant metafields. + operationId: deleteVariantsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + type: integer + description: List of metafield IDs. + responses: + '200': + description: | + Response object for metafields deletion with success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess' + '422': + description: | + Response object for metafields deletion with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE' components: schemas: categoriesTree_Resp: @@ -1744,12 +1880,12 @@ components: parent_id: type: integer description: | - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + The unique numeric ID of the categoryʼs parent. This field controls where the category sits in the tree of categories that organize the catalog. example: 25 name: type: string description: | - The name displayed for the category. Name is unique with respect to the category's siblings. + The name displayed for the category. Name is unique with respect to the categoryʼs siblings. example: Bath is_visible: type: boolean @@ -1801,21 +1937,21 @@ components: minimum: 0 type: number description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width. format: double nullable: true height: minimum: 0 type: number description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height. format: double nullable: true depth: minimum: 0 type: number description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth. format: double nullable: true is_free_shipping: @@ -1906,11 +2042,11 @@ components: type: string sku_id: type: integer - description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. + description: Read-only reference to v2 APIʼs SKU ID. Null if it is a base variant. nullable: true option_values: type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. + description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant. items: $ref: '#/components/schemas/productVariantOptionValue_Full' calculated_price: @@ -1995,21 +2131,21 @@ components: minimum: 0 type: number description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width. format: double nullable: true height: minimum: 0 type: number description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height. format: double nullable: true depth: minimum: 0 type: number description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth. format: double nullable: true is_free_shipping: @@ -2084,7 +2220,7 @@ components: - post option_values: type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. + description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant. items: $ref: '#/components/schemas/productVariantOptionValue_Full' x-required: @@ -2198,7 +2334,7 @@ components: properties: pagination: $ref: '#/components/schemas/pagination_Full' - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. x-internal: false MultiStatus: type: object @@ -2256,7 +2392,7 @@ components: Link to the next page returned in the response. description: | Pagination links for the previous and next parts of the whole collection. - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. x-internal: false metaEmpty_Full: type: object @@ -2325,7 +2461,7 @@ components: date_created: type: string description: | - Date and time of the metafield's creation. Read-Only. + Date and time of the metafieldʼs creation. Read-Only. readOnly: true format: date-time example: '2018-05-07T20:14:17+00:00' @@ -2355,6 +2491,439 @@ components: x-required: - post x-internal: false + Metafield: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + example: order + minLength: 0 + maxLength: 255 + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + enum: + - brand + - product + - variant + - category + - cart + - channel + - location + - order + - customer + example: cart + resource_id: + type: integer + description: | + The unique identifier for the resource with which the metafield is associated. + example: 424242 + readOnly: true + id: + type: integer + description: The unique identifier for the metafield. + date_created: + type: string + format: date-time + description: Date and time of the metafieldʼs creation. + example: '2022-06-16T18:39:00+00:00' + date_modified: + type: string + format: date-time + description: Date and time when the metafield was last updated. + example: '2022-06-16T18:39:00+00:00' + owner_client_id: + type: string + description: Client ID for the metafieldʼs creator. + example: asdfasdfasdfasdfasdfasdfasdf + readOnly: true + required: + - namespace + - key + - value + - permission_set + - resource_type + - resource_id + - description + - id + - date_created + - date_modified + MetaFieldCollectionResponse: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + meta: + $ref: '#/components/schemas/CollectionMeta' + x-internal: false + MetaFieldCollectionResponse_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/CollectionMeta' + MetaFieldCollectionResponsePartialSuccess_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + MetaFieldCollectionResponsePartialSuccess_DELETE: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + x-internal: false + MetaFieldCollectionDeleteResponseSuccess: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + - 124 + - 125 + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/WriteCollectionSuccessMeta' + x-internal: false + WriteCollectionPartialSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + title: Collection Meta + x-internal: false + WriteCollectionSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 3 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 0 + title: Collection Meta + x-internal: false + Total: + type: integer + description: | + Total number of items in the result set. + example: 3 + Success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + Failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + Error: + type: object + description: | + Error response payload for the BigCommerce API. + properties: + status: + type: integer + description: | + The HTTP status code for the error. + example: 422 + title: + type: string + description: | + The error title. + example: Bulk operation has failed + type: + type: string + description: | + The error type. + example: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes + errors: + $ref: '#/components/schemas/ErrorDetail' + ErrorDetail: + type: object + description: | + Error detail response payload for the BigCommerce API. + example: + "1": "Unauthorized to delete" + "2": "Metafield does not exist" + CollectionMeta: + type: object + description: Data about the response, including pagination and collection totals. + properties: + pagination: + type: object + description: Data about the response, including pagination and collection totals. + title: Pagination + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + description: | + Pagination links for the previous and next parts of the whole collection. + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + additionalProperties: true + title: Collection Meta + x-internal: false + MetafieldBase_Post: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member + required: + - permission_set + - namespace + - key + - value + MetafieldBase_Put: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member parameters: ProductIdParam: name: product_id @@ -2396,6 +2965,69 @@ components: schema: type: string default: 'application/json' + PageParam: + name: page + description: | + Specifies the page number in a limited (paginated) list of products. + required: false + in: query + schema: + type: integer + MetafieldKeyParam: + name: key + in: query + description: Filter based on a metafieldʼs key. + required: false + schema: + type: string + MetafieldKeyInParam: + name: key:in + in: query + description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + MetafieldNamespaceParam: + name: namespace + in: query + description: Filter based on a metafieldʼs namespaces. + required: false + schema: + type: string + MetafieldNamespaceInParam: + name: namespace:in + in: query + description: Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + LimitParam: + name: limit + description: | + Controls the number of items per page in a limited (paginated) list of products. + required: false + in: query + schema: + type: integer + DirectionParam: + name: direction + description: | + Sort direction. Acceptable values are: `asc`, `desc`. + required: false + in: query + schema: + type: string + enum: + - asc + - desc securitySchemes: X-Auth-Token: name: X-Auth-Token diff --git a/reference/catalog/products_catalog.v3.yml b/reference/catalog/products_catalog.v3.yml index b6630921d..402b0c8ca 100644 --- a/reference/catalog/products_catalog.v3.yml +++ b/reference/catalog/products_catalog.v3.yml @@ -42,6 +42,7 @@ servers: security: - X-Auth-Token: [] tags: + - name: Batch metafields - name: Products - name: Bulk Pricing Rules - name: Complex Rules @@ -1229,7 +1230,7 @@ paths: > The maximum number of products you can delete at one time is 250. **Example**: - To delete products with the id's of 1,2 and 3, use `DELETE /v3/catalog/products?id:in=1,2,3`. + To delete products with IDs 1,2 and 3, use `DELETE /v3/catalog/products?id:in=1,2,3`. operationId: deleteProducts parameters: - name: name @@ -2046,13 +2047,13 @@ paths: is_thumbnail: type: boolean description: | - Flag for identifying whether the image is used as the product's thumbnail. + Flag for identifying whether the image is used as the productʼs thumbnail. sort_order: maximum: 2147483647 minimum: -2147483648 type: integer description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. + The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the imageʼs new `sort_order` value will have their `sort_order`s reordered. description: type: string description: | @@ -2114,13 +2115,13 @@ paths: is_thumbnail: type: boolean description: | - Flag for identifying whether the image is used as the product's thumbnail. + Flag for identifying whether the image is used as the productʼs thumbnail. sort_order: maximum: 2147483647 minimum: -2147483648 type: integer description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. + The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the imageʼs new `sort_order` value will have their `sort_order`s reordered. description: type: string description: | @@ -2191,13 +2192,13 @@ paths: is_thumbnail: type: boolean description: | - Flag for identifying whether the image is used as the product's thumbnail. + Flag for identifying whether the image is used as the productʼs thumbnail. sort_order: maximum: 2147483647 minimum: -2147483648 type: integer description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. + The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the imageʼs new `sort_order` value will have their `sort_order`s reordered. description: type: string description: | @@ -2468,13 +2469,13 @@ paths: is_thumbnail: type: boolean description: | - Flag for identifying whether the image is used as the product's thumbnail. + Flag for identifying whether the image is used as the productʼs thumbnail. sort_order: maximum: 2147483647 minimum: -2147483648 type: integer description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. + The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the imageʼs new `sort_order` value will have their `sort_order`s reordered. description: type: string description: | @@ -2668,7 +2669,7 @@ paths: sort_order: 3 title: TOP WORKPLACES 2016 - Austin American Statesman + BigCommerce description: |- - We've been named one of Austin American-Statesman's Top WorkPlaces for the 5th year in a row! Here's what some employees have to say: + We've been named one of Austin American-Statesmanʼs Top WorkPlaces for the 5th year in a row! Hereʼs what some employees have to say: “I am given the freedom and trust to make a difference.” @@ -2735,7 +2736,7 @@ paths: example: 1 type: integer description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. + The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the videoʼs new `sort_order` value will have their `sort_order`s reordered. type: type: string description: | @@ -2787,7 +2788,7 @@ paths: minimum: -2147483648 type: integer description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. + The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the videoʼs new `sort_order` value will have their `sort_order`s reordered. type: type: string description: | @@ -2949,7 +2950,7 @@ paths: minimum: -2147483648 type: integer description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. + The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the videoʼs new `sort_order` value will have their `sort_order`s reordered. type: type: string description: | @@ -2999,7 +3000,7 @@ paths: minimum: -2147483648 type: integer description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. + The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the videoʼs new `sort_order` value will have their `sort_order`s reordered. type: type: string description: | @@ -3211,7 +3212,7 @@ paths: enabled: type: boolean description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + Flag for determining whether the rule is to be used when adjusting a productʼs price, weight, image, or availabilty. example: true stop: type: boolean @@ -3343,7 +3344,7 @@ paths: enabled: type: boolean description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + Flag for determining whether the rule is to be used when adjusting a productʼs price, weight, image, or availabilty. example: true stop: type: boolean @@ -3567,7 +3568,7 @@ paths: enabled: type: boolean description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + Flag for determining whether the rule is to be used when adjusting a productʼs price, weight, image, or availabilty. example: true stop: type: boolean @@ -3740,7 +3741,7 @@ paths: enabled: type: boolean description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + Flag for determining whether the rule is to be used when adjusting a productʼs price, weight, image, or availabilty. example: true stop: type: boolean @@ -3871,7 +3872,7 @@ paths: enabled: type: boolean description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + Flag for determining whether the rule is to be used when adjusting a productʼs price, weight, image, or availabilty. example: true stop: type: boolean @@ -5069,12 +5070,12 @@ paths: - name: key in: query description: | - Filter based on a metafield's key. + Filter based on a metafieldʼs key. schema: type: string - name: namespace in: query - description: Filter based on a metafield's namespace. + description: Filter based on a metafieldʼs namespace. schema: type: string - name: include_fields @@ -5205,7 +5206,7 @@ paths: meta: {} '409': description: | - The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client ID, namespace, key, resource_type, and resource_id. + The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique key combinations of the appʼs client ID, namespace, key, resource_type, and resource_id. content: application/json: schema: @@ -6243,7 +6244,7 @@ paths: inventory_value: type: number description: | - Total value of store's inventory. + Total value of storeʼs inventory. format: double example: 267000 primary_category_id: @@ -6285,6 +6286,142 @@ paths: $ref: '#/components/schemas/metaEmpty_Full' parameters: - $ref: '#/components/parameters/Accept' + '/catalog/products/metafields': + get: + summary: Get All Metafields + tags: + - Batch metafields + description: Get all product metafields. + operationId: getProductsMetafields + responses: + '200': + description: | + List of `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse' + '500': + description: Internal Server Error + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/MetafieldKeyParam' + - $ref: '#/components/parameters/MetafieldKeyInParam' + - $ref: '#/components/parameters/MetafieldNamespaceParam' + - $ref: '#/components/parameters/MetafieldNamespaceInParam' + - $ref: '#/components/parameters/DirectionParam' + post: + summary: Create multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: createProductsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + resource_id: + type: integer + example: 42 + description: | + The ID for the product with which the metafield is associated. + required: + - resource_id + description: '' + responses: + '200': + description: | + List of created `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + put: + summary: Update multiple Metafields + tags: + - Batch metafields + description: Update multiple metafields. + operationId: updateProductsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Put' + - type: object + properties: + id: + type: integer + example: 42 + description: | + The ID of metafield to update. + required: + - id + description: '' + responses: + '200': + description: | + List of updated `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + delete: + summary: Delete All Metafields + tags: + - Batch metafields + description: Delete all product metafields. + operationId: deleteProductsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + type: integer + description: List of metafield IDs. + responses: + '200': + description: | + Response object for metafields deletion with success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess' + '422': + description: | + Response object for metafields deletion with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE' components: schemas: productModifier_Base: @@ -6500,21 +6637,21 @@ components: minimum: 0 type: number description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width. format: double nullable: true height: minimum: 0 type: number description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height. format: double nullable: true depth: minimum: 0 type: number description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth. format: double nullable: true is_free_shipping: @@ -6603,7 +6740,7 @@ components: type: string option_values: type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. + description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant. items: $ref: '#/components/schemas/productVariantOptionValue_Full' calculated_price: @@ -6686,21 +6823,21 @@ components: minimum: 0 type: number description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width. format: double nullable: true height: minimum: 0 type: number description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height. format: double nullable: true depth: minimum: 0 type: number description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth. format: double nullable: true is_free_shipping: @@ -6867,13 +7004,13 @@ components: is_thumbnail: type: boolean description: | - Flag for identifying whether the image is used as the product's thumbnail. + Flag for identifying whether the image is used as the productʼs thumbnail. sort_order: maximum: 2147483647 minimum: -2147483648 type: integer description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. + The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the imageʼs new `sort_order` value will have their `sort_order`s reordered. description: type: string description: | @@ -6941,7 +7078,7 @@ components: maximum: 2147483647 minimum: -2147483648 description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. + The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the videoʼs new `sort_order` value will have their `sort_order`s reordered. example: 1 type: type: string @@ -7078,7 +7215,7 @@ components: enabled: type: boolean description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + Flag for determining whether the rule is to be used when adjusting a productʼs price, weight, image, or availabilty. example: true stop: type: boolean @@ -7431,11 +7568,11 @@ components: product_list_adjusts_pricing: type: boolean description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + (product_list, product_list_with_images) Flag to add the optional productʼs price to the main productʼs price. product_list_shipping_calc: type: string description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + (product_list, product_list_with_images) How to factor the optional productʼs weight and package dimensions into the shipping quote. Values: `none` - donʼt adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. example: weight enum: - none @@ -7468,7 +7605,7 @@ components: properties: pagination: $ref: '#/components/schemas/pagination_Full' - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. x-internal: false pagination_Full: title: pagination_Full @@ -7517,7 +7654,7 @@ components: Link to the next page returned in the response. description: | Pagination links for the previous and next parts of the whole collection. - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. x-internal: false metaEmpty_Full: type: object @@ -7910,11 +8047,11 @@ components: product_list_adjusts_pricing: type: boolean description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + (product_list, product_list_with_images) Flag to add the optional productʼs price to the main productʼs price. product_list_shipping_calc: type: string description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + (product_list, product_list_with_images) How to factor the optional productʼs weight and package dimensions into the shipping quote. Values: `none` - donʼt adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. example: weight enum: - none @@ -8140,7 +8277,7 @@ components: minimum: 0 type: number description: | - If entered, the sale price will be used instead of value in the price field when calculating the product's cost. + If entered, the sale price will be used instead of value in the price field when calculating the productʼs cost. format: float map_price: type: number @@ -8156,7 +8293,7 @@ components: minLength: 0 type: string description: | - Tax Codes, such as AvaTax System Tax Codes, identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to a tax provider integration, such as BigCommerce's Avalara Premium, can calculate sales taxes more accurately. Stores without a tax provider will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive. For details, please see the tax provider's documentation. + Tax Codes, such as AvaTax System Tax Codes, identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to a tax provider integration, such as BigCommerceʼs Avalara Premium, can calculate sales taxes more accurately. Stores without a tax provider will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive. For details, please see the tax providerʼs documentation. categories: type: array description: | @@ -8192,7 +8329,7 @@ components: minimum: 0 type: integer description: | - Inventory warning level for the product. When the product's inventory level drops below the warning level, the store owner will be informed. Simple inventory tracking must be enabled (see the `inventory_tracking` field) for this to take any effect. + Inventory warning level for the product. When the productʼs inventory level drops below the warning level, the store owner will be informed. Simple inventory tracking must be enabled (see the `inventory_tracking` field) for this to take any effect. inventory_tracking: type: string description: | @@ -8264,7 +8401,7 @@ components: availability: type: string description: | - Availability of the product. (Corresponds to the product's [Purchasability](https://support.bigcommerce.com/s/article/Adding-Products-v3?language=en_US#sections) section in the control panel.) Supported values: `available` - the product is available for purchase; `disabled` - the product is listed on the storefront, but cannot be purchased; `preorder` - the product is listed for pre-orders. + Availability of the product. (Corresponds to the productʼs [Purchasability](https://support.bigcommerce.com/s/article/Adding-Products-v3?language=en_US#sections) section in the control panel.) Supported values: `available` - the product is available for purchase; `disabled` - the product is listed on the storefront, but cannot be purchased; `preorder` - the product is listed for pre-orders. enum: - available - disabled @@ -8296,7 +8433,7 @@ components: condition: type: string description: | - The product condition. Will be shown on the product page if the `is_condition_shown` field's value is `true`. Possible values: `New`, `Used`, `Refurbished`. + The product condition. Will be shown on the product page if the `is_condition_shown` fieldʼs value is `true`. Possible values: `New`, `Used`, `Refurbished`. enum: - New - Used @@ -8328,7 +8465,7 @@ components: maxLength: 65535 minLength: 0 description: | - Custom meta keywords for the product page. If not defined, the store's default keywords will be used. + Custom meta keywords for the product page. If not defined, the storeʼs default keywords will be used. items: type: string meta_description: @@ -8336,7 +8473,7 @@ components: minLength: 0 type: string description: | - Custom meta description for the product page. If not defined, the store's default meta description will be used. + Custom meta description for the product page. If not defined, the storeʼs default meta description will be used. view_count: maximum: 1000000000 minimum: 0 @@ -8347,7 +8484,7 @@ components: preorder_release_date: type: string description: | - Pre-order release date. See the `availability` field for details on setting a product's availability to accept pre-orders. + Pre-order release date. See the `availability` field for details on setting a productʼs availability to accept pre-orders. format: date-time nullable: true preorder_message: @@ -8365,7 +8502,7 @@ components: is_price_hidden: type: boolean description: | - False by default, indicating that this product's price should be shown on the product page. If set to `true`, the price is hidden. (NOTE: To successfully set `is_price_hidden` to `true`, the `availability` value must be `disabled`.) + False by default, indicating that this productʼs price should be shown on the product page. If set to `true`, the price is hidden. (NOTE: To successfully set `is_price_hidden` to `true`, the `availability` value must be `disabled`.) price_hidden_label: maxLength: 200 minLength: 0 @@ -8503,7 +8640,7 @@ components: date_created: type: string description: | - Date and time of the metafield's creation. Read-Only. + Date and time of the metafieldʼs creation. Read-Only. readOnly: true format: date-time example: '2018-05-07T20:14:17+00:00' @@ -8640,6 +8777,439 @@ components: $ref: '#/components/schemas/beta5DetailedErrors' x-tags: - Models + Metafield: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + example: order + minLength: 0 + maxLength: 255 + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + enum: + - brand + - product + - variant + - category + - cart + - channel + - location + - order + - customer + example: cart + resource_id: + type: integer + description: | + The unique identifier for the resource with which the metafield is associated. + example: 424242 + readOnly: true + id: + type: integer + description: The unique identifier for the metafield. + date_created: + type: string + format: date-time + description: Date and time of the metafieldʼs creation. + example: '2022-06-16T18:39:00+00:00' + date_modified: + type: string + format: date-time + description: Date and time when the metafield was last updated. + example: '2022-06-16T18:39:00+00:00' + owner_client_id: + type: string + description: Client ID for the metafieldʼs creator. + example: asdfasdfasdfasdfasdfasdfasdf + readOnly: true + required: + - namespace + - key + - value + - permission_set + - resource_type + - resource_id + - description + - id + - date_created + - date_modified + MetaFieldCollectionResponse: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + meta: + $ref: '#/components/schemas/CollectionMeta' + x-internal: false + MetaFieldCollectionResponse_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/CollectionMeta' + MetaFieldCollectionResponsePartialSuccess_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + MetaFieldCollectionResponsePartialSuccess_DELETE: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + x-internal: false + MetaFieldCollectionDeleteResponseSuccess: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + - 124 + - 125 + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/WriteCollectionSuccessMeta' + x-internal: false + WriteCollectionPartialSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + title: Collection Meta + x-internal: false + WriteCollectionSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 3 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 0 + title: Collection Meta + x-internal: false + Total: + type: integer + description: | + Total number of items in the result set. + example: 3 + Success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + Failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + Error: + type: object + description: | + Error response payload for the BigCommerce API. + properties: + status: + type: integer + description: | + The HTTP status code for the error. + example: 422 + title: + type: string + description: | + The error title. + example: Bulk operation has failed + type: + type: string + description: | + The error type. + example: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes + errors: + $ref: '#/components/schemas/ErrorDetail' + ErrorDetail: + type: object + description: | + Error detail response payload for the BigCommerce API. + example: + "1": "Unauthorized to delete" + "2": "Metafield does not exist" + CollectionMeta: + type: object + description: Data about the response, including pagination and collection totals. + properties: + pagination: + type: object + description: Data about the response, including pagination and collection totals. + title: Pagination + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + description: | + Pagination links for the previous and next parts of the whole collection. + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + additionalProperties: true + title: Collection Meta + x-internal: false + MetafieldBase_Post: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member + required: + - permission_set + - namespace + - key + - value + MetafieldBase_Put: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member parameters: ProductIdParam: name: product_id @@ -8720,6 +9290,69 @@ components: schema: type: string default: 'application/json' + PageParam: + name: page + description: | + Specifies the page number in a limited (paginated) list of products. + required: false + in: query + schema: + type: integer + MetafieldKeyParam: + name: key + in: query + description: Filter based on a metafieldʼs key. + required: false + schema: + type: string + MetafieldKeyInParam: + name: key:in + in: query + description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + MetafieldNamespaceParam: + name: namespace + in: query + description: Filter based on a metafieldʼs namespaces. + required: false + schema: + type: string + MetafieldNamespaceInParam: + name: namespace:in + in: query + description: Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + LimitParam: + name: limit + description: | + Controls the number of items per page in a limited (paginated) list of products. + required: false + in: query + schema: + type: integer + DirectionParam: + name: direction + description: | + Sort direction. Acceptable values are: `asc`, `desc`. + required: false + in: query + schema: + type: string + enum: + - asc + - desc securitySchemes: X-Auth-Token: name: X-Auth-Token diff --git a/reference/channels.v3.yml b/reference/channels.v3.yml index ed32a7776..477a3182a 100644 --- a/reference/channels.v3.yml +++ b/reference/channels.v3.yml @@ -16,7 +16,7 @@ info: ### Platform - A channel's `type` and `platform` combination must be a valid pair as indicated in the table below. + A channelʼs `type` and `platform` combination must be a valid pair as indicated in the table below. | Platform | Accepted Type | |:--------------------|:--------------| @@ -58,7 +58,7 @@ info: ### Status - Allowed values for a channel's `status` vary by channel `type` and `platform`. + Allowed values for a channelʼs `status` vary by channel `type` and `platform`. |Type|Platform|Allowed Statuses| |--|--|--| @@ -94,14 +94,15 @@ servers: security: - X-Auth-Token: [] tags: + - name: Batch metafields - name: Channels - - name: Channel Active Theme - - name: Channel Currency Assignments - - name: Channel Listings - - name: Channel Site - - name: Channel Site Checkout Url - - name: Channel Menus - - name: Channel Metafields + - name: Metafields + - name: Menus + - name: Active Theme + - name: Currency Assignments + - name: Listings + - name: Site + - name: Site Checkout URL paths: '/channels': parameters: @@ -222,7 +223,7 @@ paths: - $ref: '#/components/parameters/channel_id_path_param' get: tags: - - Channel Active Theme + - Active Theme summary: Get a Channel Active Theme operationId: getChannelActiveTheme description: |- @@ -238,7 +239,7 @@ paths: - $ref: '#/components/parameters/Accept' get: tags: - - Channel Currency Assignments + - Currency Assignments summary: Get All Channels Currency Assignments operationId: getAllCurrencyAssignments description: Returns a list of currency assignments for all channels. @@ -247,7 +248,7 @@ paths: $ref: '#/components/responses/multiple_channels_currency_assignments_resp' post: tags: - - Channel Currency Assignments + - Currency Assignments parameters: - $ref: '#/components/parameters/ContentType' summary: Create Multiple Channels Currency Assignments @@ -269,7 +270,7 @@ paths: $ref: '#/components/responses/missing_or_invalid_multiple_channels_currency_assignments_data_resp' put: tags: - - Channel Currency Assignments + - Currency Assignments summary: Update Multiple Channels Currency Assignments parameters: - $ref: '#/components/parameters/ContentType' @@ -295,7 +296,7 @@ paths: - $ref: '#/components/parameters/channel_id_path_param' get: tags: - - Channel Currency Assignments + - Currency Assignments summary: Get Channel Currency Assignments operationId: getSingleChannelCurrencyAssignments description: Returns a list of currency assignments for a specific channel. @@ -306,7 +307,7 @@ paths: $ref: '#/components/responses/channel_not_found_resp' post: tags: - - Channel Currency Assignments + - Currency Assignments summary: Create Channel Currency Assignments parameters: - $ref: '#/components/parameters/ContentType' @@ -328,7 +329,7 @@ paths: $ref: '#/components/responses/missing_or_invalid_single_channel_currency_assignments_data_resp' put: tags: - - Channel Currency Assignments + - Currency Assignments summary: Update Channel Currency Assignments parameters: - $ref: '#/components/parameters/ContentType' @@ -350,7 +351,7 @@ paths: $ref: '#/components/responses/missing_or_invalid_single_channel_currency_assignments_data_resp' delete: tags: - - Channel Currency Assignments + - Currency Assignments summary: Delete Channel Currency Assignments operationId: deleteSingleChannelCurrencyAssignments description: 'Deletes currency assignments for a specific channel. Once done, this channel will inherit the store’s currency settings.' @@ -365,7 +366,7 @@ paths: - $ref: '#/components/parameters/channel_id_path_param' get: tags: - - Channel Listings + - Listings summary: Get Channel Listings operationId: getChannelListings description: 'Returns a list of all *Channel Listings* for a specific channel. Note that if the *Channel* is not found or there is no listing associated to the *Channel*, it will return a 200 response with empty data.' @@ -388,7 +389,7 @@ paths: $ref: '#/components/responses/invalid_filters_resp' post: tags: - - Channel Listings + - Listings summary: Create Channel Listings parameters: - $ref: '#/components/parameters/ContentType' @@ -412,7 +413,7 @@ paths: $ref: '#/components/responses/missing_or_invalid_multiple_listings_data_for_post_resp' put: tags: - - Channel Listings + - Listings summary: Update Channel Listings parameters: - $ref: '#/components/parameters/ContentType' @@ -450,7 +451,7 @@ paths: - $ref: '#/components/parameters/listing_id_path_param' get: tags: - - Channel Listings + - Listings summary: Get a Channel Listing operationId: getChannelListing description: Returns a *Channel Listing* for a specific channel. @@ -464,10 +465,10 @@ paths: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/channel_id_path_param' put: - summary: Upsert a Site's Checkout URL + summary: Upsert a Siteʼs Checkout URL tags: - - Channel Site Checkout Url - description: Creates or updates (upserts) a site's checkout URL + - Site Checkout URL + description: Creates or updates (upserts) a siteʼs checkout URL operationId: updateCheckoutUrl parameters: - $ref: '#/components/parameters/ContentType' @@ -487,35 +488,26 @@ paths: Example 1: examples: response: - value: |- - { - "id": 1, - "url": "https://kittens.mybigcommerce.com/", - "channel_id": 1, - "created_at": "2018-01-04T04:15:50.000Z", - "updated_at": "2018-01-04T04:15:50.000Z", - "urls": [ - { - "url": "https://kittens.mybigcommerce.com", - "type": "primary", - "created_at": "2022-03-22T13:08:59Z", - "updated_at": "2022-03-22T13:08:59Z" - }, - { - "url": "https://store-abc.store.bcdev", - "type": "canonical", - "created_at": "2022-03-22T13:08:59Z", - "updated_at": "2022-03-22T13:08:59Z" - }, - { - "url": "https://checkout.kittens.mybigcommerce.com", - "type": "checkout", - "created_at": "2022-03-23T10:21:11Z", - "updated_at": "2022-03-29T13:44:22Z" - } - ], - "is_checkout_url_customized": true - } + value: + id: 1 + url: 'https://kittens.mybigcommerce.com/' + channel_id: 1 + created_at: "2018-01-04T04:15:50.000Z" + updated_at: "2018-01-04T04:15:50.000Z" + urls: + - url: "https://kittens.mybigcommerce.com" + type: primary + created_at: "2022-03-22T13:08:59Z" + updated_at: "2022-03-22T13:08:59Z" + - url: 'https://store-abc.store.bcdev' + type: canonical + created_at: "2022-03-22T13:08:59Z" + updated_at: "2022-03-22T13:08:59Z" + - url: 'https://checkout.kittens.mybigcommerce.com' + type: checkout + created_at: '2022-03-23T10:21:11Z' + updated_at: '2022-03-29T13:44:22Z' + is_checkout_url_customized: true '422': description: Unprocessable Entity. Your checkout and storefront must be within the same main domain like `example.com` and `subdomain.example.com` content: @@ -541,11 +533,11 @@ paths: errors: type: object delete: - summary: Delete a Site's Checkout URL + summary: Delete a Siteʼs Checkout URL operationId: deleteCheckoutUrl description: Deletes a siteʼs checkout URL. After deletion, a shared checkout URL is used. tags: - - Channel Site Checkout Url + - Site Checkout URL responses: '200': description: OK. `data` and `meta` are empty objects. @@ -574,7 +566,7 @@ paths: '200': $ref: '#/components/responses/site_Resp' tags: - - Channel Site + - Site put: responses: '200': @@ -592,7 +584,7 @@ paths: application/json: url: 'https://example.com/' tags: - - Channel Site + - Site description: Updates a site for provided channel. post: responses: @@ -612,7 +604,7 @@ paths: url: 'http://kittens.mybigcommerce.com/' channel_id: 123 tags: - - Channel Site + - Site description: Alias of POST `/sites`. Creates a site for provided channel. delete: responses: @@ -623,10 +615,10 @@ paths: schema: type: object properties: {} - description: Deletes the Channel's site. + description: Deletes the Channelʼs site. operationId: deleteChannelSite tags: - - Channel Site + - Site summary: Delete a Channel Site '/channels/{channel_id}/channel-menus': parameters: @@ -641,7 +633,7 @@ paths: '200': $ref: '#/components/responses/channel_menus_Resp' tags: - - Channel Menus + - Menus post: responses: '200': @@ -657,7 +649,7 @@ paths: $ref: '#/components/schemas/channel_menus_Post' examples: {} tags: - - Channel Menus + - Menus description: Creates or replaces list of control panel side navigation menus for a channel. delete: responses: @@ -679,7 +671,7 @@ paths: description: Deletes control panel side navigation menus for a channel. operationId: deleteChannelMenus tags: - - Channel Menus + - Menus summary: Delete Channel Menus '/channels/{channel_id}/metafields': parameters: @@ -688,7 +680,7 @@ paths: get: summary: Get Channel Metafields tags: - - Channel Metafields + - Metafields responses: '200': $ref: '#/components/responses/metafield_200' @@ -715,7 +707,7 @@ paths: $ref: '#/components/schemas/metafield_Post' examples: {} tags: - - Channel Metafields + - Metafields description: |- Creates a channel metafield. @@ -732,7 +724,7 @@ paths: get: summary: Get a Channel Metafield tags: - - Channel Metafields + - Metafields responses: '200': $ref: '#/components/responses/metafield_200' @@ -752,7 +744,7 @@ paths: schema: $ref: '#/components/schemas/metafield_Put' tags: - - Channel Metafields + - Metafields description: |- Updates a single channel metafield. @@ -765,8 +757,124 @@ paths: '204': description: No Content tags: - - Channel Metafields + - Metafields description: Deletes a single channel metafield. + '/channels/metafields': + get: + summary: Get All Metafields + tags: + - Batch metafields + description: Get all channel metafields. + operationId: getChannelsMetafields + responses: + '200': + description: | + List of `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse' + '500': + description: Internal Server Error + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/MetafieldKeyParam' + - $ref: '#/components/parameters/MetafieldKeyInParam' + - $ref: '#/components/parameters/MetafieldNamespaceParam' + - $ref: '#/components/parameters/MetafieldNamespaceInParam' + - $ref: '#/components/parameters/DirectionParam' + post: + summary: Create multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: createChannelsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/MetafieldPost' + description: '' + responses: + '200': + description: | + List of created `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + put: + summary: Update multiple Metafields + tags: + - Batch metafields + description: Update multiple metafields. + operationId: updateChannelsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/MetafieldPut' + description: '' + responses: + '200': + description: | + List of updated `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + delete: + summary: Delete All Metafields + tags: + - Batch metafields + description: Delete all channel metafields. + operationId: deleteChannelsMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + type: integer + description: List of metafield IDs. + responses: + '200': + description: | + Response object for metafields deletion with success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess' + '422': + description: | + Response object for metafields deletion with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE' components: parameters: Accept: @@ -805,17 +913,39 @@ components: name: key in: query description: | - Filter based on a metafield's key. + Filter based on a metafieldʼs key. required: false schema: type: string + MetafieldKeyInParam: + name: key:in + in: query + description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string MetafieldNamespaceParam: name: namespace in: query - description: Filter based on a metafield's namespace. + description: Filter based on a metafieldʼs namespace. required: false schema: type: string + MetafieldNamespaceInParam: + name: namespace:in + in: query + description: Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string LimitParam: name: limit description: | @@ -826,7 +956,8 @@ components: type: integer DirectionParam: name: direction - description: Sort direction. + description: |- + Sort direction. Acceptable values are: `asc`, `desc`. required: false in: query schema: @@ -1395,7 +1526,7 @@ components: date_created: type: string description: | - Date and time of the metafield's creation. Read-Only. + Date and time of the metafieldʼs creation. Read-Only. format: date-time example: '2018-05-07T20:14:17.000Z' date_modified: @@ -1539,17 +1670,17 @@ components: name: Terrarium with fish - product_id: 100 state: pending - name: Women's Bold T-Shirt + name: Womenʼs Bold T-Shirt description: 'The same t-shirt, but not a [Sample]' variants: - product_id: 100 variant_id: 91 state: pending - name: Small women's bold t-shirt + name: Small womenʼs bold t-shirt - product_id: 100 variant_id: 92 state: pending - name: Medium women's bold t-shirt + name: Medium womenʼs bold t-shirt update_single_listing_req_example: value: - listing_id: 882998595 @@ -1575,12 +1706,12 @@ components: - listing_id: 882789362 product_id: 100 state: pending - name: Women's Bold T-Shirt + name: Womenʼs Bold T-Shirt variants: - product_id: 100 variant_id: 91 state: pending - name: Small women's bold t-shirt + name: Small womenʼs bold t-shirt multiple_channels_without_currencies_resp_example: value: data: @@ -1794,7 +1925,7 @@ components: listing_id: 882789362 product_id: 100 state: pending - name: Women's Bold T-Shirt + name: Womenʼs Bold T-Shirt description: 'The same t-shirt, but not a [Sample]' date_created: '2021-05-24T17:46:33Z' date_modified: '2021-05-24T17:46:33Z' @@ -1803,14 +1934,14 @@ components: product_id: 100 variant_id: 91 state: pending - name: Small women's bold t-shirt + name: Small womenʼs bold t-shirt date_created: '2021-05-24T17:46:33Z' date_modified: '2021-05-24T17:46:33Z' - channel_id: 664177 product_id: 100 variant_id: 92 state: pending - name: Medium women's bold t-shirt + name: Medium womenʼs bold t-shirt date_created: '2021-05-24T17:46:33Z' date_modified: '2021-05-24T17:46:33Z' meta: @@ -1929,8 +2060,8 @@ components: title: 'The following fields are invalid: type, platform' type: /api-docs/getting-started/api-status-codes errors: - type: The field 'type' can not be updated after channel is created. - platform: The field 'platform' can not be updated after channel is created. + type: "The field 'type' can not be updated after channel is created." + platform: "The field 'platform' can not be updated after channel is created." error_422_prevent_update_deleted_channel_resp_example: value: status: 422 @@ -2135,7 +2266,7 @@ components: date_created: type: string description: | - Date and time of the metafield's creation. Read-Only. + Date and time of the metafieldʼs creation. Read-Only. format: date-time example: '2018-05-07T20:14:17.000Z' date_modified: @@ -2144,6 +2275,470 @@ components: Date and time when the metafield was last updated. Read-Only. format: date-time example: '2018-05-07T20:14:17.000Z' + Metafield: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + example: order + minLength: 0 + maxLength: 255 + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + enum: + - brand + - product + - variant + - category + - cart + - channel + - location + - order + - customer + example: cart + resource_id: + type: integer + description: | + The unique identifier for the resource with which the metafield is associated. + example: 424242 + readOnly: true + id: + type: integer + description: The unique identifier for the metafield. + date_created: + type: string + format: date-time + description: Date and time of the metafieldʼs creation. + example: '2022-06-16T18:39:00+00:00' + date_modified: + type: string + format: date-time + description: Date and time when the metafield was last updated. + example: '2022-06-16T18:39:00+00:00' + owner_client_id: + type: string + description: Client ID for the metafieldʼs creator. + example: asdfasdfasdfasdfasdfasdfasdf + readOnly: true + required: + - namespace + - key + - value + - permission_set + - resource_type + - resource_id + - description + - id + - date_created + - date_modified + MetaFieldCollectionResponse: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + meta: + $ref: '#/components/schemas/CollectionMeta' + x-internal: false + MetaFieldCollectionResponse_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/CollectionMeta' + MetaFieldCollectionResponsePartialSuccess_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + MetaFieldCollectionResponsePartialSuccess_DELETE: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + x-internal: false + MetaFieldCollectionDeleteResponseSuccess: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + - 124 + - 125 + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/WriteCollectionSuccessMeta' + x-internal: false + WriteCollectionPartialSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + title: Collection Meta + x-internal: false + WriteCollectionSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 3 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 0 + title: Collection Meta + x-internal: false + Total: + type: integer + description: | + Total number of items in the result set. + example: 3 + Success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + Failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + Error: + type: object + description: | + Error response payload for the BigCommerce API. + properties: + status: + type: integer + format: int32 + description: | + The HTTP status code for the error. + example: 422 + title: + type: string + description: | + The error title describing the particular error. + example: Bulk operation has failed + type: + type: string + description: | + The error type. + example: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes + errors: + $ref: '#/components/schemas/ErrorDetail' + ErrorDetail: + type: object + description: | + Error detail response payload for the BigCommerce API. + example: + "1": "Unauthorized to delete" + "2": "Metafield does not exist" + CollectionMeta: + type: object + description: Data about the response, including pagination and collection totals. + properties: + pagination: + type: object + description: Data about the response, including pagination and collection totals. + title: Pagination + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + description: | + Pagination links for the previous and next parts of the whole collection. + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + additionalProperties: true + title: Collection Meta + x-internal: false + MetafieldBase_Post: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member + required: + - permission_set + - namespace + - key + - value + MetafieldPost: + description: | + The model for a POST to create metafield. + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + resource_id: + type: integer + example: 42 + description: | + The ID for the resource with which the metafield is associated. + required: + - resource_id + x-internal: false + MetafieldBase_Put: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member + MetafieldPut: + description: | + The model for a PUT to create metafield. + allOf: + - $ref: '#/components/schemas/MetafieldBase_Put' + - type: object + properties: + id: + type: integer + example: 42 + description: | + The ID of metafield to update. + required: + - id + x-internal: false PutCheckoutUrl: type: object properties: @@ -2342,7 +2937,7 @@ components: deprecated: true query_path: type: string - description: The value that will be passed to the app's iFrame in the URL and will allow the app to display the appropriate section within the app iFrame in the control panel. + description: The value that will be passed to the appʼs iFrame in the URL and will allow the app to display the appropriate section within the app iFrame in the control panel. deprecated: true x-examples: example-1: @@ -2616,7 +3211,7 @@ components: x-internal: false ActiveTheme: type: object - description: Details about the Channel's relationship to Themes. + description: Details about the Channelʼs relationship to Themes. properties: active_theme_uuid: type: string @@ -2688,23 +3283,6 @@ components: type: string description: Value used in the `section` query param. x-internal: false - Error: - type: object - properties: - status: - type: integer - format: int32 - description: The HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - description: Link to a list of BigCommerce API status codes. - errors: - type: object - description: Provides more details to errors. - x-internal: false MetaWithFullPagination: type: object description: 'Data about the response, including pagination.' @@ -3066,4 +3644,4 @@ components: type: string description: | Description for the metafield. - example: Location in the warehouse. \ No newline at end of file + example: Location in the warehouse. diff --git a/reference/customers.v3.yml b/reference/customers.v3.yml index ada043c7f..bf6f0664e 100644 --- a/reference/customers.v3.yml +++ b/reference/customers.v3.yml @@ -22,18 +22,20 @@ servers: security: - X-Auth-Token: [] tags: + - name: Batch metafields - name: Customers description: BigCommerce Customers API Definition. - - name: Customer Addresses - - name: Customer Attributes - - name: Customer Attribute Values - - name: Customer Form Field Values - - name: Customer Consent - - name: Customer Form Fields - - name: Customer Stored Instruments - - name: Customer Settings - - name: Customer Settings Channel - - name: Customer Validate Credentials + - name: Consent + - name: Validate Credentials + - name: Metafields + - name: Addresses + - name: Attributes + - name: Attribute Values + - name: Form Fields + - name: Form Field Values + - name: Stored Instruments + - name: Global Settings + - name: Channel Settings paths: '/customers': get: @@ -483,7 +485,7 @@ paths: '200': $ref: '#/components/responses/AddressCollectionResponse' tags: - - Customer Addresses + - Addresses post: description: |- Creates a Customer Address. Multiple customer addresses can be created in one call. @@ -578,7 +580,7 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse' tags: - - Customer Addresses + - Addresses put: description: |- Updates a Customer Address. Multiple customer addresses can be updated in one call. @@ -672,7 +674,7 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse' tags: - - Customer Addresses + - Addresses delete: description: |- Deletes a Customer Address. @@ -710,11 +712,11 @@ paths: description: '' headers: {} tags: - - Customer Addresses + - Addresses '/customers/validate-credentials': post: tags: - - Customer Validate Credentials + - Validate Credentials description: Validate a customer credentials - This endpoint has special rate limiting protections to protect against abuse. summary: Validate a customer credentials operationId: validateCustomerCredentials @@ -765,7 +767,7 @@ paths: '/customers/settings': get: tags: - - Customer Settings + - Global Settings description: Returns the global-level customer settings. summary: Get Customer Settings operationId: getCustomersSettings @@ -787,7 +789,7 @@ paths: default_customer_group_id: 1 put: tags: - - Customer Settings + - Global Settings description: Updates the customer settings on the global level. summary: Update Customer Settings operationId: updateCustomersSettings @@ -826,7 +828,7 @@ paths: '/customers/settings/channels/{channel_id}': get: tags: - - Customer Settings Channel + - Channel Settings description: |- Returns the customer settings per channel. @@ -859,7 +861,7 @@ paths: allow_global_logins: true put: tags: - - Customer Settings Channel + - Channel Settings description: |- Update the customer settings per channel @@ -1009,7 +1011,7 @@ paths: '200': $ref: '#/components/responses/CustomerAttributesResponse' tags: - - Customer Attributes + - Attributes post: description: |- Creates a Customer Attribute. Multiple customer attributes can be created in one call. @@ -1065,7 +1067,7 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse' tags: - - Customer Attributes + - Attributes put: description: |- Updates a Customer Attribute. Multiple customer attributes can be updated in one call. @@ -1114,7 +1116,7 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse' tags: - - Customer Attributes + - Attributes delete: description: |- Deletes Customer Attributes from the store. @@ -1151,7 +1153,7 @@ paths: description: '' headers: {} tags: - - Customer Attributes + - Attributes '/customers/attribute-values': get: description: Returns a list of Customer Attribute Values. Optional filter parameters can be passed in. @@ -1240,7 +1242,7 @@ paths: '200': $ref: '#/components/responses/CustomerAttributeValueCollectionResponse' tags: - - Customer Attribute Values + - Attribute Values put: description: |- Upserts Customer Attribute Values. Updates the attribute values on the Customer. Multiple customer attribute values can be updated in one call. @@ -1307,7 +1309,7 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse' tags: - - Customer Attribute Values + - Attribute Values delete: description: |- Deletes Customer Attribute Values. Deletes the attribute value from the customer. @@ -1346,7 +1348,7 @@ paths: description: '' headers: {} tags: - - Customer Attribute Values + - Attribute Values '/customers/form-field-values': get: responses: @@ -1365,7 +1367,7 @@ paths: To learn about adding and managing form fields, see [Adding and Editing Fields in the Account Signup Form](https://support.bigcommerce.com/s/article/Editing-Form-Fields). operationId: getCustomersFormFieldValues tags: - - Customer Form Field Values + - Form Field Values parameters: - name: Accept in: header @@ -1447,7 +1449,7 @@ paths: * Limit of 10 concurrent requests. operationId: updateCustomerFormFieldValues tags: - - Customer Form Field Values + - Form Field Values requestBody: content: application/json: @@ -1469,10 +1471,10 @@ paths: value: Mushrooms '/customers/{customerId}/consent': get: - description: Gets the status of a customer's consent to allow data collection by cookies and scripts while shopping on a storefront. + description: Gets the status of a customerʼs consent to allow data collection by cookies and scripts while shopping on a storefront. summary: Get Customer Consent tags: - - Customer Consent + - Consent operationId: getCustomerConsent deprecated: false responses: @@ -1497,10 +1499,10 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse' put: - description: Updates the status of a customer's consent to allow data collection by cookies and scripts while shopping on a storefront. + description: Updates the status of a customerʼs consent to allow data collection by cookies and scripts while shopping on a storefront. summary: Update Customer Consent tags: - - Customer Consent + - Consent operationId: updateCustomerConsent deprecated: false parameters: @@ -1548,7 +1550,7 @@ paths: get: summary: Get Stored Instruments tags: - - Customer Stored Instruments + - Stored Instruments description: |- Lists all available stored instruments for a customer. This list will include all types of stored instruments namely card, account and bank_account instruments @@ -1621,6 +1623,142 @@ paths: name: customerId in: path required: true + '/customers/metafields': + get: + summary: Get All Metafields + tags: + - Batch metafields + description: Get all customer metafields. + operationId: getCustomersMetafields + responses: + '200': + description: | + List of `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse' + '500': + description: Internal Server Error + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/MetafieldKeyParam' + - $ref: '#/components/parameters/MetafieldKeyInParam' + - $ref: '#/components/parameters/MetafieldNamespaceParam' + - $ref: '#/components/parameters/MetafieldNamespaceInParam' + - $ref: '#/components/parameters/DirectionParam' + post: + summary: Create multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: createCustomersMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + resource_id: + type: integer + example: 42 + description: | + The ID for the resource with which the metafield is associated. + required: + - resource_id + description: '' + responses: + '200': + description: | + List of created `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + put: + summary: Update multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: updateCustomersMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Put' + - type: object + properties: + id: + type: integer + example: 42 + description: | + The ID of metafield to update. + required: + - id + description: '' + responses: + '200': + description: | + List of updated `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + delete: + summary: Delete All Metafields + tags: + - Batch metafields + description: Delete all customer metafields. + operationId: deleteCustomersMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + type: integer + description: Metafields ID list. + responses: + '200': + description: | + Response object for metafields deletion with success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess' + '422': + description: | + Response object for metafields deletion with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE' components: parameters: customerId: @@ -1630,6 +1768,69 @@ components: description: '' schema: type: string + PageParam: + name: page + description: | + Specifies the page number in a limited (paginated) list of products. + required: false + in: query + schema: + type: integer + MetafieldKeyParam: + name: key + in: query + description: Filter based on a metafieldʼs key. + required: false + schema: + type: string + MetafieldKeyInParam: + name: key:in + in: query + description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + MetafieldNamespaceParam: + name: namespace + in: query + description: Filter based on a metafieldʼs namespaces. + required: false + schema: + type: string + MetafieldNamespaceInParam: + name: namespace:in + in: query + description: Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string + LimitParam: + name: limit + description: | + Controls the number of items per page in a limited (paginated) list of products. + required: false + in: query + schema: + type: integer + DirectionParam: + name: direction + description: | + Sort direction. Acceptable values are: `asc`, `desc`. + required: false + in: query + schema: + type: string + enum: + - asc + - desc responses: CustomerCollectionResponse: description: Customer Collection Response @@ -1676,7 +1877,8 @@ components: channel_ids: - 1 shopper_profile_id: "82511e54-4040-40fe-b742-2b25655f205b" - segment_ids: ["5bb733a9-5491-47b3-9451-9ae8d6a6bc6b"] + segment_ids: + - "5bb733a9-5491-47b3-9451-9ae8d6a6bc6b" meta: pagination: total: 0 @@ -2069,12 +2271,12 @@ components: - customer_id meta: title: Collection Meta - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. type: object properties: pagination: title: Pagination - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. type: object properties: total: @@ -2247,12 +2449,12 @@ components: title: 'Form Field Value ' meta: title: Collection Meta - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. type: object properties: pagination: title: Pagination - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. type: object properties: total: @@ -2507,7 +2709,7 @@ components: schemas: Pagination: title: Pagination - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. type: object properties: total: @@ -2535,7 +2737,7 @@ components: x-internal: false _metaCollection: title: _metaCollection - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. type: object properties: pagination: @@ -2737,7 +2939,9 @@ components: channel_ids: description: Array of channels the customer can access. type: array - example: [1,2] + example: + - 1 + - 2 items: type: integer form_fields: @@ -2839,7 +3043,7 @@ components: format: int32 value: description: |- - Attribute value. This will always be a string, regardless of the attribute's type. + Attribute value. This will always be a string, regardless of the attributeʼs type. Corresponds to `attribute_value` used in customer attribute values `GET` requests. type: string @@ -3286,7 +3490,7 @@ components: - address1 - city - country_code - description: The `address` object for the `customer` object's `addresses` array. + description: The `address` object for the `customer` objectʼs `addresses` array. x-internal: false customerAddresses_CustomerPost: title: customerAddresses_CustomerPost @@ -3374,7 +3578,7 @@ components: - address1 - city - country_code - description: The `address` object for the `customer` object's `addresses` array. + description: The `address` object for the `customer` objectʼs `addresses` array. x-internal: false customerAuthentication_PostPut: title: customerAuthentication_PostPut @@ -3735,7 +3939,7 @@ components: policy_url: type: string example: 'https://bigcommmerce.com/policy' - description: The URL for a website's privacy policy. + description: The URL for a websiteʼs privacy policy. customer_group_settings: type: object description: The settings for a collection of customers. @@ -3772,7 +3976,7 @@ components: policy_url: type: string example: 'https://bigcommmerce.com/policy' - description: The URL for a website's privacy policy. + description: The URL for a websiteʼs privacy policy. customer_group_settings: type: object description: The settings for a collection of customers. @@ -3830,3 +4034,612 @@ components: type: boolean description: indicates if the provided credentials are valid. x-internal: false + Metafield: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + example: order + minLength: 0 + maxLength: 255 + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + enum: + - brand + - product + - variant + - category + - cart + - channel + - location + - order + - customer + example: cart + resource_id: + type: integer + description: | + The unique identifier for the resource with which the metafield is associated. + example: 424242 + readOnly: true + id: + type: integer + description: The unique identifier for the metafield. + date_created: + type: string + format: date-time + description: Date and time of the metafieldʼs creation. + example: '2022-06-16T18:39:00+00:00' + date_modified: + type: string + format: date-time + description: Date and time when the metafield was last updated. + example: '2022-06-16T18:39:00+00:00' + owner_client_id: + type: string + description: Client ID for the metafieldʼs creator. + example: asdfasdfasdfasdfasdfasdfasdf + readOnly: true + required: + - namespace + - key + - value + - permission_set + - resource_type + - resource_id + - description + - id + - date_created + - date_modified + MetaFieldCollectionResponse: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + meta: + $ref: '#/components/schemas/CollectionMeta' + x-internal: false + MetaFieldCollectionResponse_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/CollectionMeta' + MetaFieldCollectionResponsePartialSuccess_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + MetaFieldCollectionResponsePartialSuccess_DELETE: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + x-internal: false + MetaFieldCollectionDeleteResponseSuccess: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + - 124 + - 125 + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/WriteCollectionSuccessMeta' + x-internal: false + WriteCollectionPartialSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + title: Collection Meta + x-internal: false + WriteCollectionSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 3 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 0 + title: Collection Meta + x-internal: false + Total: + type: integer + description: | + Total number of items in the result set. + example: 3 + Success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + Failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + Error: + type: object + description: | + Error response payload for the BigCommerce API. + properties: + status: + type: integer + description: | + The HTTP status code for the error. + example: 422 + title: + type: string + description: | + The error title. + example: Bulk operation has failed + type: + type: string + description: | + The error type. + example: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes + errors: + $ref: '#/components/schemas/ErrorDetail' + ErrorDetail: + type: object + description: | + Error detail response payload for the BigCommerce API. + example: + "1": "Unauthorized to delete" + "2": "Metafield does not exist" + CollectionMeta: + type: object + description: Data about the response, including pagination and collection totals. + properties: + pagination: + type: object + description: Data about the response, including pagination and collection totals. + title: Pagination + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + description: | + Pagination links for the previous and next parts of the whole collection. + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + additionalProperties: true + title: Collection Meta + x-internal: false + MetafieldBase_Post: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member + required: + - permission_set + - namespace + - key + - value + MetafieldBase_Put: + type: object + description: | + Common Metafield properties. + x-internal: false + properties: + permission_set: + type: string + description: | + 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. | + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + namespace: + type: string + description: | + Namespace for the metafield, for organizational purposes. + example: Sales Department + minLength: 1 + maxLength: 64 + key: + type: string + description: | + The name of the field, for example: `location_id`, `color`. + minLength: 1 + maxLength: 64 + example: Staff Name + value: + type: string + description: | + The value of the field, for example: `1`, `blue`. + minLength: 1 + maxLength: 65535 + example: Ronaldo + description: + type: string + description: | + Description for the metafields. + minLength: 0 + maxLength: 255 + example: Name of Staff Member + metafield_Full: + title: metafield_Full + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Metafield*. Read-Only. + readOnly: true + example: 6 + - $ref: '#/components/schemas/metafield_Base' + - type: object + properties: + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + example: customer + enum: + - category + - brand + - product + - variant + - customer + x-required: + - post + resource_id: + maximum: 10000000000 + minimum: 0 + type: integer + description: | + The ID of the resource with which the metafield is associated. + example: 111 + x-required: + - post + date_created: + type: string + description: | + Date and time of the metafieldʼs creation. Read-Only. + readOnly: true + format: date-time + example: '2018-05-07T20:14:17+00:00' + date_modified: + type: string + description: | + Date and time when the metafield was last updated. Read-Only. + readOnly: true + format: date-time + example: '2018-05-07T20:14:17+00:00' + x-internal: false + metafield_Base: + title: metafield_Base + type: object + description: 'Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + x-internal: false + properties: + key: + maxLength: 64 + minLength: 1 + type: string + description: | + The name of the field, for example: `location_id`, `color`. Required for POST. + example: Location + x-required: + - post + value: + maxLength: 65535 + minLength: 1 + type: string + description: | + The value of the field, for example: `1`, `blue`. Required for POST. + example: 4HG + x-required: + - post + namespace: + maxLength: 64 + minLength: 1 + type: string + description: | + Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST. + example: Warehouse Locations + x-required: + - post + permission_set: + type: string + description: |- + 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 storefront| + |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + description: + maxLength: 255 + minLength: 0 + type: string + description: | + Description for the metafields. + example: Location in the warehouse + required: + - permission_set + - namespace + - key + - value + metaEmpty_Full: + type: object + title: Response meta + properties: { } + additionalProperties: true + description: Response metadata. + metaCollection_Full: + title: metaCollection_Full + type: object + properties: + pagination: + $ref: '#/components/schemas/pagination_Full' + description: Data about the response, including pagination and collection totals. + x-internal: false + pagination_Full: + title: pagination_Full + type: object + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + description: | + Pagination links for the previous and next parts of the whole collection. + description: Data about the response, including pagination and collection totals. + x-internal: false diff --git a/reference/orders.v3.yml b/reference/orders.v3.yml index 125cfffc6..914a0ab66 100644 --- a/reference/orders.v3.yml +++ b/reference/orders.v3.yml @@ -24,6 +24,7 @@ tags: - name: Payment Actions - name: Transactions - name: Order Settings + - name: Batch metafields paths: '/orders/{order_id}/payment_actions/capture': post: @@ -96,7 +97,7 @@ paths: tags: - Transactions description: |- - Returns an **order's** transactions. + Returns an **orderʼs** transactions. **Usage Notes** * Depending on the payment method, different information will be available (not all payment gateways return full card or fraud detail). @@ -498,34 +499,24 @@ paths: Example 1: examples: response: - value: |- - { - "data": [ - { - "order_id": 1, - "total_refund_amount": 1.99, - "total_refund_tax_amount": 1.95, - "rounding": 1, - "adjustment": 0.05, - "tax_inclusive": true, - "refund_methods": [ - "" - ] - } - ], - "errors": [ - { - "order_id": 1, - "status": 422, - "error": "Refund amount is greater than remaining amount" - } - ], - "meta": { - "failure": 1, - "success": 1, - "total": 2 - } - } + value: + data: + - order_id: 1 + total_refund_amount: 1.99 + total_refund_tax_amount: 1.95 + rounding: 1 + adjustment: 0.05 + tax_inclusive: true + refund_methods: + - "" + errors: + - order_id: 1 + status: 422 + error: "Refund amount is greater than remaining amount" + meta: + failure: 1 + success: 1 + total: 2 '503': description: Every request in the batch failed. The error object describes the failure for each component request. content: @@ -617,7 +608,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/MetafieldPost' + $ref: '#/components/schemas/MetafieldBase_Post' examples: {} description: | A `Metafield` object. @@ -632,7 +623,7 @@ paths: $ref: '#/components/schemas/MetafieldResponse' '409': description: | - The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client ID, namespace, key, resource_type, and resource_id. + 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. content: application/json: schema: @@ -873,6 +864,142 @@ paths: type: string description: Channel ID required: true + '/orders/metafields': + get: + summary: Get All Metafields + tags: + - Batch metafields + description: Get all order metafields. + operationId: getOrdersMetafields + responses: + '200': + description: | + List of `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse' + '500': + description: Internal Server Error + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/MetafieldKeyParam' + - $ref: '#/components/parameters/MetafieldKeyInParam' + - $ref: '#/components/parameters/MetafieldNamespaceParam' + - $ref: '#/components/parameters/MetafieldNamespaceInParam' + - $ref: '#/components/parameters/DirectionParam' + post: + summary: Create multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: createOrdersMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + resource_id: + type: integer + example: 42 + description: | + The ID for the order with which the metafield is associated. + required: + - resource_id + description: '' + responses: + '200': + description: | + List of created `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + put: + summary: Update multiple Metafields + tags: + - Batch metafields + description: Create multiple metafields. + operationId: updateOrdersMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + id: + type: integer + example: 42 + description: | + The ID of metafield to update. + required: + - id + description: '' + responses: + '200': + description: | + List of updated `Metafield` objects. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT' + '422': + description: | + Response object for metafields creation with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT' + '500': + description: Internal Server Error + delete: + summary: Delete All Metafields + tags: + - Batch metafields + description: Delete all order metafields. + operationId: deleteOrdersMetafields + requestBody: + content: + application/json: + schema: + type: array + items: + type: integer + description: List of metafield IDs. + responses: + '200': + description: | + Response object for metafields deletion with success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess' + '422': + description: | + Response object for metafields deletion with partial success. + content: + application/json: + schema: + $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE' components: schemas: GetReturnsSettings: @@ -1110,7 +1237,7 @@ components: x-internal: false Pagination: type: object - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. title: Pagination properties: total: @@ -1293,11 +1420,11 @@ components: x-internal: false CollectionMeta: type: object - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. properties: pagination: type: object - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. title: Pagination properties: total: @@ -1351,7 +1478,7 @@ components: properties: meta: type: object - description: 'Data about the response, including pagination and collection totals.' + description: Data about the response, including pagination and collection totals. title: Pagination properties: total: @@ -1773,7 +1900,7 @@ components: properties: remaining_balance: description: | - Remaining balance of shopper's store credit. + Remaining balance of shopperʼs store credit. type: number format: float example: 35.42 @@ -1876,7 +2003,7 @@ components: properties: remaining_balance: description: | - Remaining balance of shopper's store credit. + Remaining balance of shopperʼs store credit. type: number format: float example: 35.42 @@ -2134,6 +2261,7 @@ components: Note that `refund_methods` is an array of refund methods, with each refund method being an array of payment options. For example, if the order was placed by a combination of store credit and bank deposit the refund methods would be: + ```json { "refund_methods": [ @@ -2528,7 +2656,7 @@ components: description: Reference to order ID. user_id: type: integer - description: Reference to the user's ID who create this refund. This is automatically populated by BigCommerce. + description: Reference to the userʼs ID who create this refund. This is automatically populated by BigCommerce. readOnly: true created: type: string @@ -2687,6 +2815,22 @@ components: meta: $ref: '#/components/schemas/CollectionMeta' x-internal: false + MetaFieldCollectionResponse_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/CollectionMeta' + x-internal: false MetafieldResponse: description: | Response payload for the BigCommerce API. @@ -2841,7 +2985,7 @@ components: type: string format: date-time description: | - Date and time of the metafield's creation. + Date and time of the metafieldʼs creation. example: '2022-06-16T18:39:00+00:00' date_modified: type: string @@ -2849,13 +2993,11 @@ components: description: | Date and time when the metafield was last updated. example: '2022-06-16T18:39:00+00:00' - x-internal: false - x-examples: {} - MetafieldPost: - description: | - The model for a POST to create metafield. - allOf: - - $ref: '#/components/schemas/MetafieldBase_Post' + owner_client_id: + type: string + description: Client ID for the metafieldʼs creator. + example: asdfasdfasdfasdfasdfasdfasdf + readOnly: true x-internal: false x-examples: {} MetafieldPut: @@ -2897,6 +3039,184 @@ components: x-examples: example-1: $ref: '#/components/examples/EnableMultipleOrderNotifications/value' + MetaFieldCollectionResponsePartialSuccess_POST_PUT: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + $ref: '#/components/schemas/Metafield' + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + MetaFieldCollectionResponsePartialSuccess_DELETE: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + errors: + type: array + items: + $ref: '#/components/schemas/Error' + meta: + $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' + x-internal: false + MetaFieldCollectionDeleteResponseSuccess: + type: object + description: | + Response payload for the BigCommerce API. + properties: + data: + type: array + items: + type: integer + description: | + The unique identifier for the metafield. + example: + - 123 + - 124 + - 125 + errors: + type: array + description: Empty for 200 responses. + example: [] + meta: + $ref: '#/components/schemas/WriteCollectionSuccessMeta' + x-internal: false + WriteCollectionPartialSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + title: Collection Meta + x-internal: false + WriteCollectionSuccessMeta: + type: object + description: Additional data about the response. + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 3 + success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 3 + failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 0 + title: Collection Meta + x-internal: false + Total: + type: integer + description: | + Total number of items in the result set. + example: 3 + Success: + type: integer + description: | + Total number of items that were successfully deleted. + example: 1 + Failed: + type: integer + description: | + Total number of items that failed to be deleted. + example: 2 + Error: + type: object + description: | + Error response payload for the BigCommerce API. + properties: + status: + type: integer + description: | + The HTTP status code for the error. + example: 422 + title: + type: string + description: | + The error title. + example: Bulk operation has failed + type: + type: string + description: | + The error type. + example: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes + errors: + $ref: '#/components/schemas/ErrorDetail' + ErrorDetail: + type: object + description: | + Error detail response payload for the BigCommerce API. + example: + "1": "Unauthorized to delete" + "2": "Metafield does not exist" + MetafieldPost_Batch: + description: | + The model for a POST to create metafield. + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + resource_id: + type: integer + example: 42 + description: | + The ID for the resource with which the metafield is associated. + required: + - resource_id + x-internal: false + MetafieldPut_Batch: + description: | + The model for a PUT to create metafield. + allOf: + - $ref: '#/components/schemas/MetafieldBase_Post' + - type: object + properties: + id: + type: integer + example: 42 + description: | + The ID of metafield to update. + resource_id: + type: integer + example: 42 + description: | + The ID for the resource with which the metafield is associated. + required: + - id + x-internal: false ChannelOrderSettings: type: object properties: @@ -3379,18 +3699,40 @@ components: name: key in: query description: | - Filter based on a metafield's key. + Filter based on a metafieldʼs key. required: false schema: type: string + MetafieldKeyInParam: + name: key:in + in: query + description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string MetafieldNamespaceParam: name: namespace in: query description: | - Filter based on a metafield's key. + Filter based on a metafieldʼs key. required: false schema: type: string + MetafieldNamespaceInParam: + name: namespace:in + in: query + description: Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter. + required: false + style: form + explode: false + schema: + type: array + items: + type: string LimitParam: name: limit description: |