Metadata

Metadata is a free-form JSON field that you can use to store your own data against Pinch entities. It is supported on Payers, Payments, Plans, and Subscriptions.

Format

Although it is free-form, metadata must be valid JSON: either a single object or an array of objects:

// Single object
{"myOrderId": "ORD-9876", "campaignCode": "SUMMER25"}

// Array of objects
[{"myOrderId": "ORD-9876"}, {"campaignCode": "SUMMER25"}]

You can store any key/value pairs that are useful for your integration: internal IDs, reference numbers, tags, or any other data you want to retrieve alongside the Pinch entity.

⚠️

Pinch may add objects to the metadata array internally (for special beta/accounting functionality). Design your code to tolerate receiving additional objects it didn't store, and do not rely on the array being exactly what you put in.

Supported entities

Common patterns

Linking a payment to your order

When creating a payment, include your internal order or invoice reference in metadata so you can cross-reference Pinch events against your own database:

{
  "payerId": "pyr_abc123",
  "amount": 9900,
  "description": "Invoice INV-456",
  "transactionDate": "2026-07-20",
  "metadata": "{\"orderId\": \"ORD-789\", \"invoiceRef\": \"INV-456\"}"
}

When a transfer or bank-results event arrives containing paymentId: "pmt_xyz", look up the payment via GET /payments/pmt_xyz and read the metadata to find the original order.

Linking a payer to your customer record

Store your internal customer ID on the payer so you can always find the Pinch payer for a given customer:

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "metadata": "{\"customerId\": \"CUST-001\", \"tier\": \"premium\"}"
}

Tagging subscriptions

Useful for filtering or reporting in your own system:

{
  "planId": "pln_abc123",
  "payerId": "pyr_def456",
  "metadata": "{\"contractRef\": \"CTR-2026-001\", \"salesRegion\": \"NSW\"}"
}

Accounting system matching (beta)

Metadata also powers Pinch's accounting system integration with Xero, QuickBooks, and MYOB. Use the special MetaType objects below to have Pinch automatically match your payments and payers to records in your accounting system.

⚠️

These features are in beta. Pinch may update these metadata objects; be prepared to receive additional fields.

Payment → Invoice matching

Payments created in the API can be matched to Invoices in the accounting system using 2 different methods.

• InvoiceId - This is the identifier of the Invoice in the accounting system (ie. for Xero the Invoice Id is a guid).
• InvoiceNumber - This is the text invoice number (typically what is used when displaying the invoice). This is most commonly shown in the format INV-123 but may change depending on accounting system configuration.

AccountingV1 Example

{
  "MetaType": "AccountingV1",
  "MatchInvoice": {
    "InvoiceId": "<InvoiceIdToMatch>",
    "InvoiceNumber": "<InvoiceNumberToMatch>"
  }
}

Payer → Contact matching

Payers created in the API can be matched to contacts in the accounting system using 2 different methods.

🚧

If the payer already exists in Pinch creating a new payer and matching it will not auto-merge the records and will result in duplicates.

• AccountingContactId - This is the identifier of the contact in the accounting system (ie. for Xero the Contact Id is a guid).
• Email - The email address of the contact in the accounting system to attempt to match on.

AccountingPayerV1 Example

{
  "MetaType": "AccountingPayerV1",
  "MatchPayer": {
    "AccountingContactId": "<ContactIdToMatch>",
    "Email": "<ContactEmailToMatch>"
  }
}