BigCommerce Pages (Bulk) API

openapi: 3.2.0
info:
  title: BigCommerce Pages V3 Pages (Bulk) API
  version: ''
  termsOfService: http://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  description: "## Overview\n\nA **page** appears on a **site** that is associated with a **channel**. \n\nSome pages, such as blog pages, contact forms, and plain-text or HTML pages, are web pages in the traditional sense. They contain markup (a `body`) and load at a relative page location on the site itself (the `url`). Other pages, such as link and feed pages, make external or non-visual content available from the menu of a parent page or by direct link.\n\n### Bulk operations\nAll endpoints without a `pageId` path parameter support bulk operations.\n\n### Page types\n\nThe following table describes the types of pages that the Pages API can manage:\n\n| Page Type | Description | Body |\n|:-|:|:--|\n| `page` | A user-defined plain-text page. | text |\n| `contact_form` | A user-customizable page that contains a contact form. | HTML |\n| `raw` | A user-defined page that contains HTML markup or other stringified code. | HTML, other code |\n| `blog` | A page that contains blog posts. Use caution; `blog`-type pages can only be created in the store control panel, but you may be able to change the type of a blog page to something else with this API. Use the [Store Content API](/docs/rest-content/store-content/blog-posts#create-a-blog-post) to work with blog posts and tags. | empty string |\n| `feed` | Makes RSS-syndicated content feeds available in the menu of other pages that contain markup. | — |\n| `link` | A link to an external absolute URL. Displays in the menu of other pages that contain markup. | — |"
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Pages (Bulk)
paths:
  /content/pages:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      operationId: getPages
      tags:
      - Pages (Bulk)
      description: Returns one or more content pages. This endpoint supports bulk operations.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagesCollectionResponse'
        '400':
          description: Bad Request; reasons for failure include passing query parameters that are not supported on this endpoint, but are common on other BigCommerce endpoints.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorDetailed'
        '422':
          description: Invalid input. Reasons for failure include passing supported parameters with values that have the incorrect datatype.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorItemized'
      parameters:
      - $ref: '#/components/parameters/channelIdQuery'
      - $ref: '#/components/parameters/idInQueryGet'
      - $ref: '#/components/parameters/nameQuery'
      - $ref: '#/components/parameters/nameLikeQuery'
      - $ref: '#/components/parameters/limitQuery'
      - $ref: '#/components/parameters/pageQuery'
      - $ref: '#/components/parameters/includeQuery'
      summary: BigCommerce Get Pages
    post:
      operationId: createPages
      tags:
      - Pages (Bulk)
      description: Creates one or more content pages. This endpoint supports bulk operations.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Page'
            examples:
              example-1:
                value:
                  channel_id: 1
                  name: Content Page
                  is_visible: false
                  parent_id: 0
                  sort_order: 0
                  type: page
                  body: <div>Hello World!</div>
                  is_homepage: false
                  meta_title: My Content page
                  meta_keywords: string
                  meta_description: string
                  search_keywords: string
                  url: /my-content-page
        description: ''
        required: true
      responses:
        '201':
          $ref: '#/components/responses/HTTP201CreatePages'
        '207':
          $ref: '#/components/responses/HTTP207Response'
        '422':
          description: 'The input was not valid. This is the result of missing required fields or other invalid arguments. See the response for more details.


            When making bulk requests, an invalid input in any one entry will cause the whole request to return 422. The entries that are valid will still be created.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorDetailed'
      parameters:
      - $ref: '#/components/parameters/includeQuery'
      - $ref: '#/components/parameters/ContentType'
      summary: BigCommerce Create Pages
    put:
      operationId: updatePages
      tags:
      - Pages (Bulk)
      description: Updates one or more content pages. This endpoint supports bulk operations.
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/PagePutBulk'
              - type: array
                items:
                  $ref: '#/components/schemas/PagePutBulk'
      responses:
        '200':
          description: 'Updated.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagesCollectionResponse'
              examples:
                update meta descriptions for two pages:
                  value:
                    data:
                    - id: 20
                      channel_id: 1
                      name: all about powder detergents
                      meta_title: ''
                      is_visible: false
                      parent_id: 0
                      sort_order: 0
                      meta_keywords: null
                      type: page
                      meta_description: cornpone
                      is_homepage: false
                      is_customers_only: false
                      search_keywords: ''
                    - id: 19
                      channel_id: 1
                      name: sign up to dream big
                      meta_title: ''
                      email: ''
                      is_visible: false
                      parent_id: 0
                      sort_order: 0
                      meta_keywords: null
                      contact_fields: ''
                      type: contact_form
                      meta_description: arugula
                      is_homepage: false
                      is_customers_only: false
                      search_keywords: ''
                    meta: {}
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorBrief'
              examples:
                example-1:
                  value:
                    status: 0
                    title: string
                    type: string
        '422':
          description: The input was not valid. This is the result of missing required fields or other invalid arguments. See the response for more details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorDetailed'
              examples:
                missing required field for type raw:
                  value:
                    status: 422
                    title: Input is invalid
                    type: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
                    detail: 'missing the required field: body'
      parameters:
      - $ref: '#/components/parameters/includeQuery'
      - $ref: '#/components/parameters/ContentType'
      summary: BigCommerce Update Pages
    delete:
      operationId: deletePages
      tags:
      - Pages (Bulk)
      description: 'Deletes one or more content pages. This endpoint supports bulk operations.


        > #### Warning

        > **Pay attention to query parameters**

        > If you attempt to delete multiple pages by passing more than one page ID to `id:in` and one or more of them does not exist, you will receive a 404 response. However, the pages corresponding to the page IDs that do exist will still be deleted.'
      responses:
        '204':
          $ref: '#/components/responses/HTTP204'
        '404':
          description: Not Found. One of more of the pages specified for deletion did not exist. Specified pages that did exist were successfully deleted.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorBrief'
              examples:
                Page not found:
                  value:
                    status: 404
                    title: A Page was not found with an ID of 100
                    type: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
        '422':
          description: Invalid input. See response for details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ResponseErrorDetailed'
              examples:
                Missing ID:
                  value:
                    status: 422
                    title: Input is invalid
                    type: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
                    detail: 'missing the required field: id'
      parameters:
      - $ref: '#/components/parameters/idInQueryDelete'
      summary: BigCommerce Delete Pages
components:
  parameters:
    ContentType:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
    idInQueryGet:
      schema:
        type: string
      in: query
      name: id:in
      description: A comma-separated string of page IDs to fetch. Supports bulk operations. If none of the page IDs passed exist, the query will return an empty `data` array.
    Accept:
      name: Accept
      in: header
      required: true
      schema:
        type: string
        default: application/json
    nameLikeQuery:
      schema:
        type: string
      in: query
      name: name:like
      description: Return only pages whose `name` or `body` contain the supplied string.
    channelIdQuery:
      schema:
        type: integer
      in: query
      name: channel_id
      description: Return only pages associated with the specified channel.
    pageQuery:
      schema:
        type: integer
      in: query
      name: page
      description: The ordered grouping of results to return. See `meta.pagination.current_page` in the response body.
    includeQuery:
      schema:
        type: string
        enum:
        - body
      in: query
      name: include
      description: Include the requested property in the response. The `body` property returns the page’s markup, text, or raw content.
    idInQueryDelete:
      schema:
        type: string
      in: query
      name: id:in
      description: 'Request deletion of multiple pages by passing a comma-separated string of corresponding page IDs. Supports bulk operations. '
      required: true
    limitQuery:
      schema:
        type: integer
      in: query
      name: limit
      description: The number of results to return per request. See `meta.pagination.per_page` in the response body.
    nameQuery:
      schema:
        type: string
      in: query
      name: name
      description: Name of the page.
  schemas:
    searchKeywords:
      type: object
      properties:
        search_keywords:
          type:
          - string
          - 'null'
          description: 'Comma-separated list of keywords that shoppers can use to locate this page when searching the store.

            '
          example: trousers,pockets,luxury
          default: '""'
          readOnly: false
    ResponseMeta:
      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.

            '
          properties:
            total:
              type: integer
              description: 'Total number of items in the result set.

                '
            count:
              type: integer
              description: 'Total number of items in the collection response.

                '
            per_page:
              type: integer
              description: 'The amount of items returned in the collection per page, controlled by the limit parameter.

                '
            current_page:
              type: integer
              description: 'The page you are currently on within the collection.

                '
            total_pages:
              type: integer
              description: 'The total number of pages in the collection.

                '
            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.

                    '
                next:
                  type: string
                  description: 'Link to the next page returned in the response.

                    '
    typeRaw:
      description: ''
      allOf:
      - $ref: '#/components/schemas/anyTypePage'
      - $ref: '#/components/schemas/searchKeywords'
      - properties:
          body:
            type:
            - string
            - 'null'
            description: 'HTML or variable that populates the element of this page, in default/desktop view. Required in a `POST` request if the page type is `raw`.

              '
            example: <div>Hello World!</div>
          content_type:
            type: string
            description: The MIME type of the page body.
            example: text/html
        required:
        - body
    pageMeta:
      type: object
      properties:
        meta_title:
          type:
          - string
          - 'null'
        meta_keywords:
          description: 'Comma-separated list of SEO-relevant keywords to include in the element of this page.

            '
          default: '""'
          type:
          - string
          - 'null'
        meta_description:
          type:
          - string
          - 'null'
          default: '""'
          description: 'Description contained within the element of this page.

            '
    PagePutBulk:
      type: object
      description: Properties of the page modification request body.
      properties:
        name:
          type: string
          description: 'The name of the page. Must be unique.

            '
          minLength: 1
          maxLength: 100
          example: My Store Page
        is_visible:
          type: boolean
          description: "Boolean value that specifies the visibility of the page in the storefront’s navigation menu.\n          \n          \nIndicates whether the page is available to users and visible in any menus.\n"
        parent_id:
          type: integer
          description: 'ID of any parent Web page.

            '
          example: 0
          default: 0
        sort_order:
          type: integer
          description: 'Specifies the order in which the page is displayed on the storefront. (Lower integers specify earlier display.)

            '
          example: 0
          default: 0
        type:
          type: string
          description: 'Specifies the type of the page. The following values are possible;


            |Value|Description|

            |-|-|

            | `blog` | blog page. Read-only; blog pages can only be created in the store control panel. |

            |`contact_form`|hosts the store''s contact form|

            |`link`|link to another absolute URL|

            |`page`|user-defined plain-text page|

            |`raw`|page that contains markup, such as HTML.|

            |`rss_feed`|contains syndicated content from an RSS feed|'
          example: page
          enum:
          - page
          - raw
          - contact_form
          - feed
          - link
          - blog
        is_homepage:
          type: boolean
          description: 'Boolean value that specifies whether this page is the storefront’s home page.

            '
        is_customers_only:
          type: boolean
          description: 'Boolean value. If this value is set to `true`, this page will not be visible when the user is logged in to the store control panel.

            '
        id:
          type: integer
          description: The ID of the target page.
        email:
          type: string
          description: 'Applicable when the page type is `contact_form`: contact email address that receives messages sent via the form. Must be unique.'
          maxLength: 255
        meta_title:
          type:
          - string
          - 'null'
        body:
          type:
          - string
          - 'null'
          description: 'HTML or variable that populates the element of this page, in default/desktop view. Required in a `POST` request if the page type is `raw`.

            '
          example: <div>Hello World!</div>
        feed:
          type: string
          description: 'The URL of the RSS feed. Required in a `POST` request if the page type is `rss_feed`.

            '
        link:
          type: string
          description: 'Required in a `POST` request to create a link if the page type is `link`.

            '
        contact_fields:
          type: string
          description: 'Applicable when the page type is `contact_form`: comma-separated list of keywords representing the fields enabled in the control panel for storefront display. Possible fields include:


            |Field|Description|

            |-|-|

            |`fullname`|Full name of the customer submitting the form|

            |`phone`|Customer’s phone number, as submitted on the form|

            |`companyname`|Customer’s submitted company name|

            |`orderno`|Customer’s submitted order number|

            |`rma`|Customer’s submitted RMA (Return Merchandise Authorization) number|

            '
          example: fullname,companyname,phone,orderno,rma
        meta_keywords:
          description: 'Comma-separated list of SEO-relevant keywords to include in the element of this page.

            '
          default: ''
          type:
          - string
          - 'null'
        meta_description:
          type:
          - string
          - 'null'
          description: 'Description contained within the element of this page.

            '
        search_keywords:
          type:
          - string
          - 'null'
          description: 'Comma-separated list of keywords that shoppers can use to locate this page when searching the store.

            '
          example: trousers,pockets,luxury
        url:
          type: string
          description: 'Relative URL on the storefront for this page.

            '
          example: /my-store-page
        channel_id:
          type: integer
          description: 'The ID of the channel where this page should be shown.

            '
          example: 12
          default: 0
      required:
      - id
    typeLink:
      description: ''
      allOf:
      - $ref: '#/components/schemas/anyTypePage'
      - properties:
          link:
            type: string
            description: The link for the page type `link`.
        required:
        - link
    typeFeed:
      description: ''
      allOf:
      - $ref: '#/components/schemas/anyTypePage'
      - $ref: '#/components/schemas/pageMeta'
      - $ref: '#/components/schemas/searchKeywords'
      - properties:
          feed:
            type: string
            description: 'The URL of the RSS feed. Required in a `POST` request if the page type is `rss_feed`.

              '
        required:
        - feed
    PageBase:
      type: object
      description: Common Page properties.
      properties:
        name:
          type: string
          description: 'The name of the page. Must be unique.

            '
          minLength: 1
          maxLength: 100
          example: My Store Page
        is_visible:
          type: boolean
          description: "Determines the visibility of the page in the storefront’s navigation menu.\n\nBoolean value that specifies the visibility of the page in the storefront’s navigation menu.\n          \nIndicates whether the page is available to users and visible in any menus.\n"
        parent_id:
          type: integer
          description: 'ID of any parent Web page.

            '
          example: 0
          default: 0
        sort_order:
          type: integer
          description: 'Determines the order in which the page is displayed on the storefront. (Lower integers specify earlier display.)

            '
          example: 0
          default: 0
        type:
          type: string
          description: 'Determines the type of the page.


            |Value|Description|

            |-|-|

            | `blog` | blog page. Read-only; blog pages can only be created in the store control panel. |

            |`contact_form`|hosts the store''s contact form|

            |`link`|link to another absolute URL|

            |`page`|user-defined plain-text page|

            |`raw`|page that contains markup, such as HTML.|

            |`rss_feed`|contains syndicated content from an RSS feed|'
          example: page
          enum:
          - page
          - raw
          - contact_form
          - feed
          - link
          - blog
        is_homepage:
          type: boolean
          description: 'Determines whether this page is the storefront’s home page.

            '
        is_customers_only:
          type: boolean
          description: 'If `true`, this page will only be visible to customers that are logged in to the store.

            '
      required:
      - name
      - type
    ResponseErrorBrief:
      type: object
      description: 'Error payload for the BigCommerce API.

        '
      properties:
        status:
          description: 'The HTTP status code.

            '
          type: integer
        title:
          description: 'The error title describing the particular error.

            '
          type: string
        type:
          type: string
      required:
      - status
    typeBlog:
      description: ''
      allOf:
      - $ref: '#/components/schemas/anyTypePage'
      - $ref: '#/components/schemas/pageMeta'
      - $ref: '#/components/schemas/searchKeywords'
      - properties:
          url:
            type: string
            description: 'Relative URL on the storefront for this page.

              '
            example: /blog/
    anyTypePage:
      type: object
      description: 'Properties of all Pages V3 pages.

        '
      properties:
        id:
          type: integer
          readOnly: true
        channel_id:
          type: integer
          readOnly: true
        name:
          type: string
          description: The name of the page. Must be unique.
          minLength: 1
          maxLength: 100
          uniqueItems: true
          example: About Our Company
          readOnly: false
        is_visible:
          type: boolean
          example: true
          default: true
          description: A boolean value that controls whether the page is available to users or visible in any navigation menus.
        parent_id:
          type: integer
          description: ID of the parent page, if any.
          example: 0
          default: 0
        sort_order:
          type: integer
          description: Determines the order in which the page is displayed in the parent page’s menu. Pages with lower integers display earlier.
          example: 0
        type:
          type: string
          description: Determines the type of page. See [Pages v3 page types](/docs/rest-content/pages#page-types) for more about the differences.
          example: page
          enum:
          - page
          - raw
          - contact_form
          - feed
          - link
          - blog
        is_homepage:
          type: boolean
          description: Determines whether this page loads at the siteʼs root route. For example, at `https://example.com/`.
          default: false
        is_customers_only:
          type: boolean
          description: When `true`, this page is not visible to merchant users who are signed in to the store control panel.
          default: false
        url:
          type: string
          description: 'Relative URL on the storefront for this page.

            '
          example: /my-store-page
      required:
      - name
      - type
    PagesCollectionResponse:
      description: 'Response payload for the BigCommerce API.

        '
      type: object
      title: ''
      properties:
        data:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/typePage'
            - $ref: '#/components/schemas/typeBlog'
            - $ref: '#/components/schemas/typeContactForm'
            - $ref: '#/components/schemas/typeFeed'
            - $ref: '#/components/schemas/typeRaw'
            - $ref: '#/components/schemas/typeLink'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ResponseErrorDetailed:
      type: object
      description: 'Error payload for the BigCommerce API.

        '
      properties:
        status:
          description: 'The HTTP status code.

            '
          type: integer
        title:
          description: 'The error title describing the particular error.

            '
          type: string
        type:
          type: string
        detail:
          type: string
      required:
      - status
    ResponseErrorItemized:
      type: object
      description: 'Error payload for the BigCommerce API.

        '
      title: ResponseErrorItemized
      properties:
        status:
          description: 'The HTTP status code.

            '
          type: integer
        title:
          description: 'The error title describing the particular error.

            '
          type: string
        type:
          type: string
        errors:
          type: array
          items:
            type: string
      required:
      - status
    Page:
      allOf:
      - type: object
        properties:
          email:
            type: string
            description: 'Applicable when the page type is `contact_form`: contact email address that receives messages sent via the form. Must be unique.'
            maxLength: 255
            default: ''
          meta_title:
            type:
            - string
            - 'null'
          body:
            type:
            - string
            - 'null'
            description: 'HTML or variable that populates this page’s element, in default/desktop view. Required in a `POST` request if the page type is `raw`.

              '
            example: <div>Hello World!</div>
          feed:
            type: string
            description: 'The URL of the RSS feed. Required in a `POST` request if the page type is `rss_feed`.

              '
          link:
            type: string
            description: 'Required in a `POST` request to create a link if the page type is `link`.

              '
          contact_fields:
            type: string
            description: 'Applicable when the page type is `contact_form`: comma-separated list of keywords representing the fields enabled in the control panel for storefront display. Possible fields include:


              |Field|Description|

              |-|-|

              |`fullname`|Full name of the customer submitting the form|

              |`phone`|Customer’s phone number, as submitted on the form|

              |`companyname`|Customer’s submitted company name|

              |`orderno`|Customer’s submitted order number|

              |`rma`|Customer’s submitted RMA (Return Merchandise Authorization) number|

              '
            example: fullname,orderno,rma
            default: ''
          meta_keywords:
            description: 'Comma-separated list of SEO-relevant keywords to include in the page’s element.

              '
            default: ''
            type:
            - string
            - 'null'
          meta_description:
            type:
            - string
            - 'null'
            description: 'Description contained within this page’s element.

              '
          search_keywords:
            type:
            - string
            - 'null'
            description: 'Comma-separated list of keywords that shoppers can use to locate this page when searching the store.

              '
            example: trousers,pockets,luxury
          url:
            type: string
            description: 'Relative URL on the storefront for this page.

              '
            example: /my-store-page
          channel_id:
            type: integer
            description: 'The Id of the channel where this page should be shown.

              '
            example: 12
            default: 1
      - $ref: '#/components/schemas/PageBase'
      title: ''
      description: ''
    typePage:
      description: 'Schema for a Pages V3 page with `type: page`

        '
      allOf:
      - $ref: '#/components/schemas/anyTypePage'
      - $ref: '#/components/schemas/pageMeta'
      - $ref: '#/components/schemas/searchKeywords'
    typeContactForm:
      description: ''
      allOf:
      - $ref: '#/components/schemas/anyTypePage'
      - $ref: '#/components/schemas/pageMeta'
      - $ref: '#/components/schemas/searchKeywords'
      - properties:
          email:
            type: string
            description: 'Applicable when the page type is `contact_form`: contact email address that receives messages sent via the form. Must be unique.'
            maxLength: 255
          contact_fields:
            type: string
            description: 'A comma-separated list of the contact field forms that are enabled in the store control panel for display on the subject storefront. Possible fields include:


              | Field | Description |

              |:|:|

              | `fullname` | The full name of the customer submitting the form. |

              | `phone` | The customer’s phone number. |

              | `companyname` | The customer’s company name. |

              | `orderno` | A field that lets customers specify a subject order number. |

              | `rma` | A customer’s submitted RMA (Return Merchandise Authorization) number. |

              '
            example: fullname,companyname,phone,orderno,rma
  responses:
    HTTP207Response:
      description: Multiple operations have occurred 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 has failed.
      content:
        application/json:
          schema: {}
    HTTP201CreatePages:
      description: "Created.\n\nResponse.data will inherit the datatype of the request. A single entry passed as an object will return an object for the data property. Any number of entries passed in an array will return an array for the data property.\n\nProperties associated with a page `type` that are not required to create an entry will be created with default values. \n\nWhen you make bulk requests, an invalid input in a

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-pages-bulk-api-openapi.yml