Core Resources

Metafields

Metafields allow users to add additional information to other resources. They can be used for adding custom fields to objects, and are useful for storing specialized information.

2 additions in V2, marked New

Everything marked New also works when you send X-Recharge-Version: 2021-11.

Endpoints

POST/metafields
GET/metafields/{id}
PUT/metafields/{id}
DELETE/metafields/{id}
GET/metafields

#The metafield object

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

You can extend the responses of some of these objects by appending the include?=metafields as part of your GET request.
cf. Extending responses for more info.

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_idinteger
Unique numeric identifier of the owner_resource.
owner_resourcestring
Objects which support Metafields
Possible values
addressstorecustomersubscriptionordercharge
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.
Possible values
stringintegerjson_string

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 a metafield for a specific object.

Scopeswrite_customerswrite_subscriptionswrite_orderswrite_stores

There is a limit of 50 metafields per owner_id.
You need to have WRITE rights to the resource you want to create a Metafield for.

Returns 201. The required scope depends on owner_resource: write_customers for address and customer, write_subscriptions for subscription, write_orders for charge and order, and write_stores for store. namespace and key are limited to 50 characters, value to 1000 characters, and an owner can have at most 50 metafields.

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.
Possible values
addressstorecustomersubscriptionordercharge
valuestringRequired
The content of the metafield.
value_typestringRequired
The type of the value parameter.
Possible values
stringintegerjson_string

POST/metafields

curl -X POST 'https://api.rechargeapps.com/metafields' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Version: v2' \
  -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 a 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>

Scopesread_customersread_subscriptionsread_ordersstore_info

The required scope depends on the owner_resource of the metafield: read_customers for address and customer, read_subscriptions for subscription, read_orders for charge and order, and store_info for store.

GET/metafields/{id}

curl 'https://api.rechargeapps.com/metafields/33' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'X-Recharge-Version: v2'

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 a metafield based on a specified owner_resource.

Scopeswrite_customerswrite_subscriptionswrite_orderswrite_stores

Returns 200. The required scope depends on the owner_resource of the metafield; changing owner_resource requires the write scope of both the current and the new owner resource. The namespace and key of an existing metafield cannot be changed.

Body parameters

descriptionstring
Description of the metafield.
owner_idinteger
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.
Possible values
addressstorecustomersubscriptionordercharge
valuestring
The content of the metafield.
value_typestring
The type of the value parameter.
Possible values
stringintegerjson_string

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' \
  -H 'X-Recharge-Version: v2' \
  -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 based on a specified id.

Scopeswrite_customerswrite_subscriptionswrite_orderswrite_stores

The required scope depends on the owner_resource of the metafield: write_customers for address and customer, write_subscriptions for subscription, write_orders for charge and order, and write_stores for store.

DELETE/metafields/{id}

curl -X DELETE 'https://api.rechargeapps.com/metafields/6' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'X-Recharge-Version: v2'

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.

Scopesread_customersread_subscriptionsread_ordersstore_info

owner_resource is required unless cursor is passed. The required scope depends on owner_resource: read_customers for address and customer, read_subscriptions for subscription, read_orders for charge and order, and store_info for store.

Query parameters

cursorstringNew
Return either the next or previous page of metafields using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor.
limitstring
Amount of results.
(default:50) (maximum: 250).
Default 50Maximum 250
namespacestring
A category or container that differentiates your metadata from other metafields.
owner_idinteger
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.
Possible values
addressstorecustomersubscriptionordercharge
pagestringDeprecated
Page to show.
Default 1
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.
sort_bystringNew
Sort listed Metafields in a specific order. Available sort options: id-asc, id-desc, updated_at-asc, updated_at-desc. Defaults to updated_at-desc.
Possible values
id-ascid-descupdated_at-ascupdated_at-desc

GET/metafields

curl 'https://api.rechargeapps.com/metafields?owner_resource=address&limit=3' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -H 'X-Recharge-Version: v2'

Response

{
  "next_cursor": "next_cursor",
  "previous_cursor": "previous_cursor",
  "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"
    }
  ]
}