comecerodocs
Concepts

Meta data

Store your own data on Comecero carts, orders, customers, products and more with the meta field, and carry it from a cart or invoice to the order.

Most objects have a meta field where you can keep your own data, such as an ID from your own system or how a shopper found you. Comecero stores it and gives it back, but never acts on it.

Set meta

Send meta when you create or update an object. It can be a string or a JSON object.

Request
curl -X POST "https://api.comecero.com/api/v1/customers" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "meta": { "crm_id": "C-10442", "source": "spring-campaign" }
  }'

An object is the better choice, even for one value, because you can add more keys later. Objects can hold numbers, strings, arrays and other objects:

{
  "meta": {
    "crm_id": "C-10442",
    "visits": 12,
    "tags": ["wholesale", "newsletter"]
  }
}

Rules

  • meta can be up to 2,048 characters, counted as JSON.
  • On invoices and invoice items, meta must be an object, not a string.
  • An update replaces meta as a whole. To change one key, read the object, change its meta and send all of it back. Send "meta": null to clear it.
  • Do not store card numbers, passwords or other secrets in meta. It comes back to every token that can read the object, and a limited token can read the objects it is tied to.

Where you can use it

Objects you create or update through the API take meta, among them carts and cart items, invoices and invoice items, customers, products, payments, refunds, subscriptions, subscription plans, shipments and addresses. Each endpoint page shows whether meta is accepted.

From cart or invoice to order

When a cart or an invoice is paid, its meta is copied to the new order, and each item's meta is copied to the matching order item. This lets you collect data during checkout and find it on the order.

# Tag the cart during checkout
curl -X POST "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "meta": { "campaign": "spring-sale" } }'

After payment, the order has the same value:

{
  "object": "order",
  "order_id": "6622-NXKHE-858",
  "meta": { "campaign": "spring-sale" }
}

The order's meta arrives with the order created webhook, so your server can act on it without another call.

Next steps

On this page