Thanks for being patient while we implement your feedback to improve the developer experience.

Get Metafields

GET /orders/{order_id}/metafields

Request

Gets a Metafield object list, by order_id.

The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID.

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.

  • key in query - string

    Filter based on a metafield's key.

  • namespace in query - string

    Filter based on a metafield's key.

  • direction in query - string

    Sort direction. Acceptable values are: asc, desc.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/orders/[order_id]/metafields' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

An array of metafields and metadata.

Body

object | application/json

Response payload for the BigCommerce API.

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

Create Metafields

POST /orders/{order_id}/metafields

Request

Creates an order Metafield.

The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID.

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.

A Metafield object.

Body

application/json

The model for a POST to create metafield.

  • permission_set    string
    required

    Determines the visibility and writeability of the field by other API consumers.

    ValueDescription
    app_onlyPrivate to the app that owns the field
    readVisible to other API consumers
    writeOpen for reading and writing by other API consumers
    read_and_sf_accessVisible to other API consumers, including on storefront
    write_and_sf_accessOpen for reading and writing by other API consumers, including on storefront

    Allowed: app_only | read | write | read_and_sf_access | write_and_sf_access

  • namespace    string
    required

    Namespace for the metafield, for organizational purposes.

    >= 1 characters<= 64 characters

    Example: Sales Department

  • key    string
    required

    The name of the field, for example: location_id, color.

    >= 1 characters<= 64 characters

    Example: Staff Name

  • value    string
    required

    The value of the field, for example: 1, blue.

    >= 1 characters<= 65535 characters

    Example: Ronaldo

  • description    string

    Description for the metafields.

    >= 0 characters<= 255 characters

    Example: Name of Staff Member

    Response

    A Metafield object.

    Body

    application/json

    Response payload for the BigCommerce API.

    • data

      Allows app partners to write custom data to various resources in the API.

    • meta      object

      Data about the response, including pagination and collection totals.

      example

      {
  "data": {
    "permission_set": "app_only",
    "namespace": "Sales Department",
    "key": "Staff Name",
    "value": "Ronaldo",
    "description": "order",
    "resource_type": "order",
    "id": 0,
    "date_created": "2022-06-16T18:39:00+00:00",
    "date_modified": "2022-06-16T18:39:00+00:00"
  },
  "meta": {
    "total": 36,
    "count": 36,
    "per_page": 50,
    "current_page": 1,
    "total_pages": 1,
    "links": {
      "previous": "string",
      "current": "?page=1&limit=50",
      "next": "string"
    }
  }
}

      Get a Metafield

      GET /orders/{order_id}/metafields/{metafield_id}

      Request

      Gets a Metafield, by order_id.

      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.

      • order_id in path - integer - required

        The ID of the Order to which the transactions belong.

      • metafield_id in path - integer - required

        The ID of the Metafield.

      example

      curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/orders/[order_id]/metafields/[metafield_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

      Response

      A Metafield object.

      Body

      application/json

      Response payload for the BigCommerce API.

      • data

        Allows app partners to write custom data to various resources in the API.

      • meta        object

        Data about the response, including pagination and collection totals.

        example

        {
  "data": {
    "permission_set": "app_only",
    "namespace": "Sales Department",
    "key": "Staff Name",
    "value": "Ronaldo",
    "description": "order",
    "resource_type": "order",
    "id": 0,
    "date_created": "2022-06-16T18:39:00+00:00",
    "date_modified": "2022-06-16T18:39:00+00:00"
  },
  "meta": {
    "total": 36,
    "count": 36,
    "per_page": 50,
    "current_page": 1,
    "total_pages": 1,
    "links": {
      "previous": "string",
      "current": "?page=1&limit=50",
      "next": "string"
    }
  }
}

        Update a Metafield

        PUT /orders/{order_id}/metafields/{metafield_id}

        Request

        Updates a Metafield object.

        The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID.

        Authentication

        • X-Auth-Token in header - required

        Parameters

        • store_hash in path - string
        • metafield_id in path - integer - required

          The ID of the Metafield.

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

          The MIME type of the request body.

        A Metafield object.

        Body

        application/json

        The model for a PUT to update metafield.

        • permission_set          string
          required

          Determines the visibility and writeability of the field by other API consumers.

          ValueDescription
          app_onlyPrivate to the app that owns the field
          readVisible to other API consumers
          writeOpen for reading and writing by other API consumers
          read_and_sf_accessVisible to other API consumers, including on storefront
          write_and_sf_accessOpen for reading and writing by other API consumers, including on storefront

          Allowed: app_only | read | write | read_and_sf_access | write_and_sf_access

        • namespace          string
          required

          Namespace for the metafield, for organizational purposes.

          >= 1 characters<= 64 characters

          Example: Sales Department

        • key          string
          required

          The name of the field, for example: location_id, color.

          >= 1 characters<= 64 characters

          Example: Staff Name

        • value          string
          required

          The value of the field, for example: 1, blue.

          >= 1 characters<= 65535 characters

          Example: Ronaldo

        • description          string

          Description for the metafields.

          >= 0 characters<= 255 characters

          Example: Name of Staff Member

          example

          {
  "permission_set": "app_only",
  "namespace": "Sales Department",
  "key": "Staff Name",
  "value": "Ronaldo",
  "description": "Name of Staff Member"
}

          Response

          A metafield and metadata.

          Body

          application/json

          Response payload for the BigCommerce API.

          • data

            Allows app partners to write custom data to various resources in the API.

          • meta            object

            Data about the response, including pagination and collection totals.

            example

            {
  "data": {
    "permission_set": "app_only",
    "namespace": "Sales Department",
    "key": "Staff Name",
    "value": "Ronaldo",
    "description": "order",
    "resource_type": "order",
    "id": 0,
    "date_created": "2022-06-16T18:39:00+00:00",
    "date_modified": "2022-06-16T18:39:00+00:00"
  },
  "meta": {
    "total": 36,
    "count": 36,
    "per_page": 50,
    "current_page": 1,
    "total_pages": 1,
    "links": {
      "previous": "string",
      "current": "?page=1&limit=50",
      "next": "string"
    }
  }
}

            Delete a Metafield

            DELETE /orders/{order_id}/metafields/{metafield_id}

            Request

            Deletes a Metafield.

            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.

            • order_id in path - integer - required

              The ID of the Order to which the transactions belong.

            • metafield_id in path - integer - required

              The ID of the Metafield.

            example

            curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/orders/[order_id]/metafields/[metafield_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

            Response

            An empty response.