API
GuidesGet API token
You’re viewing the reference for API version 2021-01.See the latest version, 2021-11 →
Core Resources

Metafields

BigCommerceCustomRCS
We now have metafields endpoint on our API!

Metafields feature allows you to add additional information to other resources. They can be used for adding custom fields to objects, and are useful for storing specialized information.
Endpoints

#The metafield object

BigCommerceCustomRCS
Metafields feature allows you to add additional information to other resources. They can be used for adding custom fields to objects, and are useful for storing specialized information.

Attributes

  • idinteger
    Unique numeric identifier for the metafield.
  • created_atdatetime
    The date and time when the metafield was created.
  • descriptionstring
    Description of the metafield.
  • keystring
    The name of the metafield.
  • namespacestring
    A category or container that differentiates your metadata from other metafields.
  • owner_idstring
    Unique numeric identifier of the owner resource.
  • owner_resourcestring
    The owner of the resource can be one of the following values: address, store, customer, subscription, order, charge. There may be more objects added in the future.
  • updated_atdatetime
    The date and time when the metafield was last updated.
  • valuestring
    The content of the metafield.
  • value_typestring
    The type of the value parameter.
The metafield object
{
  "metafield": {
    "id": 33,
    "created_at": "2018-11-07T14:00:10",
    "description": "customer_phone_number",
    "key": "phone_number",
    "namespace": "personal_info",
    "owner_id": 18301938,
    "owner_resource": "customer",
    "updated_at": "2018-11-07T14:00:10",
    "value": "3103103101",
    "value_type": "integer"
  }
}

#Create a metafield

POST/metafields
Creates metafield for specific object.

Note:There is a limit of 50 metafields per owner_id.

Body parameters

  • descriptionstring
    Description of the metafield.
  • keystringRequired
    The name of the metafield.
  • namespacestringRequired
    A category or container that differentiates your metadata from other metafields.
  • owner_idintegerRequired
    Unique numeric identifier of the owner resource.
  • owner_resourcestringRequired
    The owner of the resource can be one of the following values: address, store, customer, subscription, order, charge. There may be more objects added in the future.
  • valuestringRequired
    The content of the metafield.
  • value_typestringRequired
    The type of the value parameter. Valid values are "string", "json_string" and "integer"
POST/metafields
curl -X POST 'https://api.rechargeapps.com/metafields' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "metafield": {
    "description": "customer_phone_number",
    "key": "phone_number",
    "namespace": "personal_info",
    "owner_resource": "customer",
    "owner_id": 18301938,
    "value_type": "integer",
    "value": "3103103101"
  }
}'
Response
{
  "metafield": {
    "id": 33,
    "created_at": "2018-11-07T14:00:10",
    "description": "customer_phone_number",
    "key": "phone_number",
    "namespace": "personal_info",
    "owner_id": 18301938,
    "owner_resource": "customer",
    "updated_at": "2018-11-07T14:00:10",
    "value": "3103103101",
    "value_type": "integer"
  }
}

#Retrieve a metafield

GET/metafields/{id}
Retrieves a single metafield based on specified id.

## HTTP request examples

GET /metafields/<metafield_id>
In addition to that, you can retrieve them by “subscription_id” by using:
GET /metafields?owner_resource=subscription&owner_id=<subscription_id>
GET/metafields/{id}
curl 'https://api.rechargeapps.com/metafields/33' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "metafield": {
    "id": 33,
    "created_at": "2018-11-07T14:00:10",
    "description": "customer_phone_number",
    "key": "phone_number",
    "namespace": "personal_info",
    "owner_id": 18301938,
    "owner_resource": "customer",
    "updated_at": "2018-11-07T14:00:10",
    "value": "3103103101",
    "value_type": "integer"
  }
}

#Update a metafield

PUT/metafields/{id}
Updates metafield based on specified owner resource.

Body parameters

  • descriptionstring
    Description of the metafield.
  • owner_idstring
    Unique numeric identifier of the resource.
  • owner_resourcestring
    The owner of the resource can be one of the following values: address, store, customer, subscription, order, charge. There may be more objects added in the future.
  • valuestring
    The content of the metafield.
  • value_typestring
    The type of the value parameter. Valid values are "string", "json_string" and "integer"
PUT/metafields/{id}
curl -X PUT 'https://api.rechargeapps.com/metafields/33' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "metafield": {
    "description": "phone_number_of_customer",
    "owner_id": 18293088,
    "owner_resource": "customer",
    "value": "0333103133",
    "value_type": "integer"
  }
}'
Response
{
  "metafield": {
    "id": 33,
    "created_at": "2018-11-07T14:00:10",
    "description": "customer_phone_number",
    "key": "phone_number",
    "namespace": "personal_info",
    "owner_id": 18301938,
    "owner_resource": "customer",
    "updated_at": "2018-11-07T14:00:10",
    "value": "3103103101",
    "value_type": "integer"
  }
}

#Delete a metafield

DELETE/metafields/{id}
Delete a metafield
DELETE/metafields/{id}
curl -X DELETE 'https://api.rechargeapps.com/metafields/6' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{}

#List metafields

GET/metafields
Retrieves a list of metafields.

## HTTP request examples

GET /metafields?owner_resource=<owner_resource>
GET /metafields?owner_resource=subscription&owner_id=<subscription_id>
GET /metafields?owner_resource=customer&owner_id=<customer_id>
GET /metafields?owner_resource=store&owner_id=<store_id>

When getting metafields, you must specify owner_resource in the URL. It can be address, store, customer, subscription, order, charge

You can list metafields that are created for all subscription objects using:
GET /metafields?owner_resource=subscription - owner_id in the response will be the ID of the subscription.

Metafields are filterable by any of the following parameters:

Query parameters

  • limitstring
    Amount of results.
    (default:50) (maximum: 250).
    Default 50Maximum 250
  • namespacestring
    A category or container that differentiates your metadata from other metafields.
  • owner_idstring
    Unique numeric identifier of the owner resource.
  • owner_resourcestring
    The owner of the resource can be one of the following values: address, store, customer, subscription, order, charge. There may be more objects added in the future.
  • pagestringDeprecated
    Page to show.
    Page-based pagination has been deprecated but still available to use for pages up to a 100. If you need data past this point, use cursor pagination.
GET/metafields
curl 'https://api.rechargeapps.com/metafields?owner_resource=store&limit=3' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "metafields": [
    {
      "id": 33,
      "created_at": "2018-11-07T14:00:10",
      "description": "customer_phone_number",
      "key": "phone_number",
      "namespace": "personal_info",
      "owner_id": 18301938,
      "owner_resource": "customer",
      "updated_at": "2018-11-07T14:00:10",
      "value": "3103103101",
      "value_type": "integer"
    },
    {
      "id": 15,
      "created_at": "2018-11-05T12:59:30",
      "description": "desc lorem ipsum",
      "key": "marjan",
      "namespace": "nmsp2c",
      "owner_id": 17868054,
      "owner_resource": "customer",
      "updated_at": "2018-11-05T15:48:42",
      "value": "5",
      "value_type": "integer"
    },
    {
      "id": 9,
      "created_at": "2018-11-05T12:47:27",
      "description": "desc lorem ipsum",
      "key": "marjan",
      "namespace": "nmspc",
      "owner_id": 17868054,
      "owner_resource": "customer",
      "updated_at": "2018-11-05T12:47:27",
      "value": "5",
      "value_type": "integer"
    }
  ]
}

#Count metafields

GET/metafields/count
Retrieves a number of metafields for some specific query parameter.

## HTTP request examples

GET /metafields/count?owner_resource=<owner_resource>

When getting metafields, you must specify owner_resource in the URL. It can be address, store, customer, subscription, order, charge

Query parameters

  • namespacestring
    A category or container that differentiates your metadata from other metafields.
  • owner_idstring
    Unique numeric identifier of the owner resource.
  • owner_resourcestring
    The owner of the resource can be one of the following values: address, store, customer, subscription, order, charge. There may be more objects added in the future.

Response attributes

GET/metafields/count
curl 'https://api.rechargeapps.com/metafields/count?owner_resource=store' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "count": 3
}