BigCommerce
Theme & Content APIs
Placement

Widgets

Create a Placement

POST /content/placements

Request

Creates a Placement.

Template Files

To view the list of values accepted by the template_file property, including custom templates, see Placements.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

application/json
  • widget_uuid
    string
    required

    A widget identifier.

  • template_file
    string
    required

    The template file that you would like to target.

  • channel_id
    integer

    The id of the channel on which to create this placement. Defaults to the first channel created on the store.

    Example: 1

  • entity_id
    string

    The identifier of a page you would like to target. For product pages, choose product ID. For category pages, choose category ID. Home page does not support entity_id.

  • sort_order
    integer

    The sort order to control the position of a content widget in a region.

  • region
    string

    The name of the region in which to insert content widgets.

  • status
    string

    Sets the placement as either inactive or active.

    Allowed: inactive | active

    Default: inactive

    example

    Response

    Body

    object | application/json
    • data

    • meta
      object

      Response metadata.

    response

    Get All Placements

    GET /content/placements

    Request

    Returns a list of Placements.

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • page in query - integer

      Specifies the page number in a limited (paginated) list of products.

    • limit in query - integer

      Controls the number of items per page in a limited (paginated) list of products.

    • widget_template_kind in query - string

      The kind of widget template.

    • template_file in query - string

      The template file, for example: pages/home.

    • widget_uuid in query - string

      The identifier for a specific widget.

    • widget_template_uuid in query - string

      The identifier for a specific widget template.

    • channel_id:in in query - string

      A comma-separated list of channel ids to filter the results by.

    • site_id:in in query - string

      A comma-separated list of site IDs to filter the results by.

    example

    Response

    Body

    object | application/json
    • data
      array[object]

    • meta
      object

      Data about the response, including pagination and collection totals.

    response

    Get a Placement

    GET /content/placements/{uuid}

    Request

    Returns a single Placement.

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string - required

      The MIME type of the response body.

    • uuid in path - string - required

      The identifier for a specific placement.

    example

    Response

    Body

    object | application/json
    • data

    • meta
      object

      Response metadata.

    response

    Update a Placement

    PUT /content/placements/{uuid}

    Request

    Updates a Placement.

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • Content-Type in header with default of application/json - string - required

      The MIME type of the request body.

    Body

    application/json
    • template_file
      string

      The template file that you would like to target.

    • widget_uuid
      string

      A widget identifier.

    • channel_id
      integer

      The ID of the channel on which this placement exists.

    • entity_id
      string

      The identifier of a page you would like to target. For product pages, choose product ID. For category pages, choose category ID. Home page does not support entity_id.

    • sort_order
      integer

      The sort order to control the position of a content widget in a region.

    • region
      string

      The name of the region in which to insert content widgets.

    • status
      string

      Sets the placement as either inactive or active.

      Allowed: inactive | active

      Default: inactive

      example

      Response

      Body

      object | application/json
      • data

      • meta
        object

        Response metadata.

      response

      Delete a Placement

      DELETE /content/placements/{uuid}

      Request

      Deletes a Placement.

      Authentication

      • X-Auth-Token in header - required

      Parameters

      • store_hash in path - string
      • Accept in header with default of application/json - string - required

        The MIME type of the response body.

      • uuid in path - string - required

        The identifier for a specific placement.

      example

      Response

      An empty response.

      Did you find what you were looking for?