Metadata and your own IDs

Flint resources carry two places for your own data: metadata, a map of string pairs, and external_reference_id, an identifier from your system. Both are yours to set and read.

Metadata#

A metadata map holds up to 50 key-value pairs, all strings:

• Keys are 1 to 256 Unicode code points, and values are 1 to 4,096.
• Keys and values together take at most 32,768 bytes of UTF-8.
• Values can't be empty strings.
• Keys starting with flint_ are reserved for Flint. You can't write them, and reads never return them.

A create sends the whole map, and omitting metadata stores none. A map written before these limits existed may not satisfy them.

Update metadata#

A PATCH merges your changes into the stored map. The update routes take a patch, so you send only the keys you are changing:

• Omit metadata to keep the map as it is.
• A key with a string value sets it, and a key with null deletes it.
• Deleting a key that isn't there is allowed, so a patch can delete more keys than the map holds.
• {} changes nothing.
• null for the whole field clears every key.

The limits apply to the map after the merge.

curl -X PATCH https://api.withflintpay.com/v1/orders/ord_1kmn0aExample \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: order-tag-ord_1kmn0aExample-1" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "campaign": "spring_drop",
      "legacy_tag": null
    }
  }'

This sets campaign, deletes legacy_tag, and leaves every other key alone. Product options and their values are the exception: they are replaced as members of the options array, not patched. On a retained option or option value, omitting metadata, sending null, or sending {} all clear it, so send the full map you want to keep. The field's reference says which behavior it has.

Where metadata goes#

Metadata stays on the resource you set it on. Two places show it elsewhere:

• A payment link's metadata is copied to every order the link creates. See Payment links.
• Metadata you set on an order rides on the order and comes back in its webhook, which is how the Next.js guide matches a payment to your cart. See Accept a payment with Next.js.

External references#

external_reference_id is your identifier for the resource in another system, up to 255 characters. It isn't unique: two resources can share one, and Flint doesn't reject a repeat. It also isn't a duplicate guard. To make a retry safe, send an Idempotency-Key; see Idempotency.

Packages and shipments pair the reference with external_system, the name of the system it belongs to, and external_reference_id requires it.

Find records by your IDs#

Forty list routes accept external_reference_id as an exact-match filter, so you can find the record you tagged:

curl -G https://api.withflintpay.com/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "external_reference_id=shop-1042"

To find a write after a lost response, 28 list routes accept idempotency_key, the Idempotency-Key you sent. Matching is exact and case-sensitive, and an empty list doesn't prove the operation had no effect.

No list filters by metadata. To look records up by one of your values, put it in external_reference_id, or keep your own index from the IDs you store.

Bring IDs from Stripe or Square#

Migrating from Stripe and Migrating from Square store each provider's ID in external_reference_id and look it up with the filter above.

Next steps#