> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercy-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata

> Attachez vos propres données à un objet, comme un numéro de commande.

`metadata` garde vos propres repères sur un objet : un numéro de commande, l'id d'un client dans votre système. Mercy Pay les renvoie tels quels dans les réponses et dans les webhooks.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://mercy-pay.com/api/v1/checkout_sessions \
  -H "Authorization: Bearer mp_sandbox_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "XAF",
    "metadata": { "order_id": "CMD-2041", "store": "Douala Akwa" }
  }'
```

## Où les utiliser

`metadata` est accepté sur les sessions de checkout, les paiements, les retraits, les liens de paiement, les plans, les abonnements et les clients.

Deux objets reprennent ceux d'un autre :

* un paiement reprend la `metadata` de sa session de checkout. Le webhook `payment.succeeded` vous dit donc directement quelle commande est payée ;
* une facture reprend celle de son abonnement.

## Limites

* 50 clés au plus ;
* une clé fait 40 caractères au plus ;
* une valeur est un texte, un nombre ou un booléen de 500 caractères au plus. Un objet ou une liste est refusé.

Ne mettez jamais de donnée sensible dans `metadata` : ni mot de passe, ni numéro de carte.

## Modifier

Sur un client, `PATCH` fusionne clé par clé : une clé envoyée à `null` est retirée, les autres restent. `"metadata": null` retire toutes les clés.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH https://mercy-pay.com/api/v1/customers/cus_c71d0e5a3b2f4e8a9c1d5f6a7b8c9d01 \
  -H "Authorization: Bearer mp_sandbox_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "segment": null, "city": "Douala" } }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.