API Reference

The Trailing Paper API gives your store, POS system, or custom application direct access to card payments, invoicing, and payout data for your Trailing Paper merchant account. The API is built on REST principles — all requests and responses use JSON, authentication is via a Bearer token, and standard HTTP status codes indicate success or failure.

This reference documents every available endpoint with full request/response schemas, code examples in four languages, and detailed error descriptions.

Who this is for

This API is for merchants and developers building integrations on top of a Trailing Paper account. Common use cases:

• Charging a customer's card from a custom checkout or e-commerce storefront
• Creating and sending invoices programmatically from ERP or accounting software
• Pulling payout and settlement data into business intelligence dashboards
• Automating customer record creation and payment history lookups

Base URL

API versioning

The current API version is v1. Breaking changes will be introduced only with advance notice via email to the address on your account. Non-breaking additions (new fields, new endpoints) may be made at any time.

Authentication

All API requests are authenticated with an API key passed as a Bearer token in the Authorization header. Your API key provides full access to your merchant account — never expose it in client-side code, public repositories, or browser requests.

Getting your API key

API keys are managed in your dashboard → API Keys. You can create multiple keys with distinct labels (one per integration), see when each was last used, and revoke any key individually without affecting others.

Key format

Unauthenticated requests

Any request with a missing, malformed, or revoked API key returns 401 Unauthorized:

Environments

All API requests currently target the live production environment. A sandbox environment with test card numbers and no real money movement is planned for a future release.

Making Requests

Required headers

Request body

POST request bodies must be JSON-encoded. application/x-www-form-urlencoded and multipart are not supported. Omitting Content-Type: application/json on a POST will result in a 400 response.

Response format

All responses are JSON. Successful responses return the resource object. Error responses always include an error key with a human-readable description of the problem. Field-level validation errors may return error as an object keyed by field name.

HTTPS only

All API requests must use HTTPS. HTTP requests will be rejected or redirected. TLS 1.2+ is required.

Idempotency

POST requests to the API — especially /api/charge — support idempotent retries via the Idempotency-Key header. If a network failure, timeout, or unexpected disconnect prevents you from receiving a response, you can retry the exact same request with the same key and be guaranteed no duplicate charge is created.

How it works

When you send a request with an Idempotency-Key, the server stores the response against that key. If you retry within 24 hours, the stored response is returned immediately without reprocessing the request. After 24 hours the key expires and can be reused for a new unrelated request.

Format

Any string up to 255 characters is accepted. UUID v4 format is recommended to guarantee uniqueness across your system.

Errors & Status Codes

The API uses conventional HTTP status codes. Codes in the 2xx range indicate success. Codes in the 4xx range indicate a problem with your request. Codes in the 5xx range indicate an error on our end.

Error response shape

All non-2xx responses return a consistent error envelope. Validation errors may return the error value as an object:

Rate Limits

API requests are rate-limited to 100 requests per minute per API key. Requests that exceed this limit receive 429 Too Many Requests with a Retry-After header.

Handling 429 responses

Implement exponential backoff when you receive a 429. Read the Retry-After header (in seconds) and wait at least that long before retrying. Do not hammer the API — multiple rapid retries will extend your lockout window.

Higher limits

If your integration requires throughput beyond 100 req/min, contact support@trailingpaper.com to discuss a higher-limit arrangement.

Create a Charge

Creates a payment transfer against a tokenized card. The charge flows through Finix and settles to your linked bank account on the standard payout schedule (typically T+2 business days). You must have an approved merchant account for charges to succeed.

Amounts are specified in the smallest currency unit — cents for USD. A charge of $99.99 is "amount": 9999. The minimum chargeable amount is $0.50 (50).

A newly created charge starts in PENDING state. It transitions to SUCCEEDED or FAILED asynchronously, typically within a few seconds. Use webhooks to receive real-time state-change notifications rather than polling.

Request

Headers

Body parameters

Response — 201 Created

Returns the created transfer object on success.

Error responses

List Payments

Returns a paginated list of all charges made through your merchant account, sorted by creation time descending. Supports filtering by status, date range, and amount.

Retrieve a Payment

Returns a single payment transfer by Finix transfer ID. Use this to check the current status of a charge after creation.

Tokenize a Card

Tokenizes a customer's payment details and returns a payment_instrument_id for use with Create a Charge. Raw card data must never pass through your servers.

Create an Invoice

Creates an invoice and optionally sends it to the customer by email. Returns the invoice object including a unique hosted payment link the customer can use to pay by card.

List Invoices

Returns a paginated list of all invoices for your account, with filters for status (draft, sent, paid, overdue) and date range.

Retrieve an Invoice

Returns a single invoice by ID, including line items, payment status, and the hosted payment URL.

Create a Customer

Creates a customer record in your Trailing Paper account. Customers can be attached to invoices and used to look up payment history and stored payment instruments.

List Customers

Returns a paginated list of all customers for your account, searchable by name or email.

Sync API

The Trailing Paper Sync API enables bidirectional data exchange between your Trailing Paper account and external platforms — e-commerce stores, ERPs, marketplaces, and custom systems. Pull your TP data into your store, push your store's data back, or run a full bidirectional sync in a single call.

What you can sync

Base URL

https://trailingpaper.com/api/sync

Upsert semantics

All POST endpoints use upsert logic. If a record with the same external_id or matching key field (SKU, email, etc.) already exists, it is updated. Otherwise a new record is created. Every response includes created, updated, and errors counts.

Sync API Authentication

The Sync API uses the same API key as every other Trailing Paper endpoint — no separate credentials. One key gives your external system access to payments, sync pull, and sync push.

Getting a key

Navigate to Settings → API Keys and generate a new key. Keys are automatically scoped to your active company, so the external system syncs data into the correct account.

Authenticating requests

Pass your key as a standard Bearer token on every request — the same header you use for the payment API:

Authorization: Bearer tp_live_your_key_here

What a key can do

Products

Pull all products from your Trailing Paper account, or push products from an external system into TP. Records are matched and upserted by SKU.

GET — Pull products from TP

Returns all active product records for your company, including SKU, name, price, stock quantity, category, and image URL.

Response

{
  "items": [
    {
      "id": 42,
      "sku": "SKU-1042",
      "name": "Classic Widget Pro",
      "description": "Heavy-duty all-purpose widget",
      "price": "49.99",
      "stock_quantity": 200,
      "category": "Hardware",
      "image_path": "https://trailingpaper.com/uploads/items/classic-widget-pro.jpg",
      "is_active": 1,
      "created_at": "2025-11-14T18:32:00Z"
    }
  ]
}

POST — Push products into TP

Send an array of product objects to create or update records. Matched by sku if it exists, otherwise by name.

Request body

Response

{
  "created": 3,
  "updated": 12,
  "deleted": 0,
  "errors": []
}

Customers

Pull or push customer/buyer records. Records are matched by email when available, or by external_id.

GET — Pull customers

Returns all customers for your company including contact details and billing address.

POST — Push customers

Request body fields

Vendors

Pull or push vendor records. Matched by email or name.

POST — Push vendors

Request body fields

Orders

Push orders from your store into Trailing Paper. Each order is converted into an invoice. Line items, customer lookup, and payment recording are all handled automatically.

POST — Push orders

Request body fields

Response

{
  "created": 2,
  "updated": 1,
  "errors": []
}

Purchase Orders

Pull purchase orders from TP or push inbound purchase orders from your procurement system. Matched by source_po_id or po_number.

POST — Push purchase orders

Request body fields

Expenses

Pull or push expense records. Useful for syncing platform fees, shipping costs, or ad spend from external sources into your TP financials.

POST — Push expenses

Request body fields

Ledger Entries

Pull or push general ledger entries. Use this to sync accounting journal entries from an external ERP or accounting system.

POST — Push ledger entries

Request body fields

Credit Memos

Pull or push credit memo records for returns, adjustments, or store credit.

POST — Push credit memos

Request body fields

Card Processing Config

Discovery endpoint for downstream commerce sites that want to render the in-browser card form and route charges through your Trailing Paper merchant account. Returns the application id, environment, and availability flag your client-side script needs — so you don't have to copy-paste credentials onto every site.

Authenticate with the same X-TP-Sync-Key header used for the rest of the sync API. Cache the response for ~12 hours; invalidate when you rotate the sync key.

Request

GET /api/sync/finix-config HTTP/1.1
Host: trailingpaper.com
X-TP-Sync-Key: tp_live_xxxxxxxxxxxxxxxx
Accept: application/json

Response

{
  "success": true,
  "available": true,
  "application_id": "APij8YKTk1dcUwswCDdc2AtG",
  "env": "sandbox",
  "platform_merchant_available": true,
  "company_merchant_state": "APPROVED"
}

Response fields

Charge Synced Order

Charges a Trailing Paper invoice that was created via an earlier POST /api/sync/orders push. Designed for downstream checkouts that tokenize cards client-side via Finix.js and want the resulting transfer, payment record, and ledger entry to land on the synced TP invoice.

Authenticate with X-TP-Sync-Key. Idempotent — identical retries return the existing transfer rather than double-charging.

Request

POST /api/sync/charge-order HTTP/1.1
Host: trailingpaper.com
X-TP-Sync-Key: tp_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "external_id": "315",
  "external_source": "redacted",
  "payment_instrument_id": "TKxxxxxxxxxxxxxxxx",
  "amount": 194.65
}

Request body fields

Success response

{
  "success": true,
  "transfer_id": "TRxxxxxxxxxxxxxxxx",
  "state": "PENDING",
  "payment_id": 4421,
  "invoice_id": 1293,
  "amount": 194.65
}

Response fields

Failure responses

All failures return JSON with success: false and a human-readable error. Common codes:

Recommended call order

1. Tokenize the card client-side via Finix.js (Finix.PaymentForm — see the integration playbook in /docs/cc-checkout-integration-playbook.md).
2. Create the order in your store and push it to TP via POST /api/sync/orders. Wait for 200.
3. Call POST /api/sync/charge-order with the token.
4. On success: mark the order paid, fire fulfillment hooks, send the receipt email.
5. On failure: leave the order unpaid and surface "card declined." Do not send a receipt email.

Create Invoice

Service-style invoice creator for downstream tools (e.g. the Papaya dashboard's rev-share billing) that need to bill arbitrary line items rather than e-commerce orders. Auto-creates the customer if it isn't already in your TP company. Idempotent on external_id.

Authenticate with X-TP-Sync-Key.

Request

POST /api/sync/invoice HTTP/1.1
Host: trailingpaper.com
X-TP-Sync-Key: tp_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "customer": {
    "id": 1301,
    "external_source": "papaya-dashboard",
    "external_id": "site-9",
    "name": "Wheyk",
    "email": "billing@wheyk.com"
  },
  "items": [
    { "description": "Revenue share — April 2026", "quantity": 1, "unit_price": 1234.56 }
  ],
  "issue_date": "2026-05-01",
  "due_date":   "2026-05-15",
  "notes": "5% revenue share on $24,691.20 in net sales (Apr 1–30, 2026).",
  "payment_methods": ["zelle"],
  "external_source": "papaya-dashboard",
  "external_id": "rev-share-9-2026-04"
}

Customer matching priority

1. customer.id — explicit pairing. If supplied, TP uses that customer record. Returns 422 if the id isn't in your company.
2. customer.external_source + customer.external_id — for callers that maintain their own keying.
3. customer.email — case-sensitive exact match.
4. Case-insensitive exact match on customer.name within the same company.
5. If no match, a new customer is created from the provided fields.

Payment method whitelist

Pass payment_methods as an array of method keys to restrict which options appear on the public invoice page. Accepted aliases: credit_card / card, bank / bank_transfer / ach / wire, zelle, venmo, cash. Omit the field to leave all methods enabled (the default allow_* toggles on the invoice).

Idempotency

If external_id is set and an invoice already exists with the same external_source + external_id in your company, TP returns the existing invoice (with "already_existed": true) instead of creating a duplicate. Safe to retry on network blips.

Success response

{
  "success": true,
  "already_existed": false,
  "invoice_id": 1305,
  "invoice_number": "INV-00043",
  "customer_id": 1301,
  "balance_due": 1234.56,
  "total": 1234.56,
  "status": "unpaid",
  "public_link": "https://trailingpaper.com/invoice/view/abc123…",
  "public_token": "abc123…",
  "external_source": "papaya-dashboard",
  "external_id": "rev-share-9-2026-04"
}

Send Invoice Email

Triggers the same email flow that the manual "Send Invoice" button uses on the TP UI — uses the company's email template, refreshes the public invoice link, stamps last_sent_at. Intended for downstream tools that previously created the invoice as a draft via POST /api/sync/invoice and want a separate review-then-send step.

Authenticate with X-TP-Sync-Key.

Request

POST /api/sync/invoice/1305/send HTTP/1.1
Host: trailingpaper.com
X-TP-Sync-Key: tp_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "to": ["billing@wheyk.com"],
  "note": "Optional personal message rendered in the email body."
}

Request body fields

Success response

{
  "success": true,
  "invoice_id": 1305,
  "sent_to": ["billing@wheyk.com"],
  "sent_at": "2026-05-01 09:15:42"
}

Customer Search

Lightweight typeahead for downstream UIs that let users link an external entity (a site, a tenant, a user) to an existing TP customer. Matches against name or email within your company. Returns up to 25 customers ordered by name. Auth: X-TP-Sync-Key.

Request

GET /api/sync/customers/search?q=cellular HTTP/1.1
Host: trailingpaper.com
X-TP-Sync-Key: tp_live_xxxxxxxxxxxxxxxx
Accept: application/json

Query params

Success response

{
  "success": true,
  "items": [
    {
      "id": 1301,
      "name": "Amp Cellular Longevity LLC",
      "email": "drmike@ampsportsmed.com",
      "external_source": "",
      "external_id": ""
    }
  ]
}

Pair an external entity with the returned id, then pass it as customer.id when calling POST /api/sync/invoice to bill that customer directly without creating a duplicate.

Full Bidirectional Sync

Full sync endpoints combine a GET (pull from your store) and a POST (push from TP) in a single atomic call. Use these for scheduled nightly syncs or on-demand reconciliation.

Full sync response

{
  "pulled": {
    "created": 8,
    "updated": 34,
    "deleted": 0,
    "errors": []
  },
  "pushed": 42
}

Triggering from the dashboard

You can also trigger full syncs from the Settings → Company APIs page using the sync buttons — no code required.

Webhook Events

Trailing Paper sends webhook notifications to your registered HTTPS endpoint when events occur on your account. Webhooks are the recommended way to track async state changes — particularly transfer.succeeded and transfer.failed, since charges start as PENDING and finalize asynchronously.

Event object structure

Event types

Best practices

• Respond with 200 OK within 5 seconds. Do heavy processing asynchronously.
• Use the transfer_id in the event payload to look up the charge in your system.
• Make your handler idempotent — the same event may be delivered more than once.
• Always verify the webhook signature (see below) before processing.

Verifying Signatures

Every webhook delivery will include a X-TP-Signature header containing an HMAC-SHA256 signature of the raw request body using your webhook secret. Verifying this signature is critical — it proves the request originated from Trailing Paper and not a third party.

Object Reference

Transfer

Returned by POST /api/charge. Represents a single card payment transaction.

Changelog

April 24, 2026 — v1.0

• New: POST /api/charge — create a card charge via Finix Payment Instrument ID
• New: API key management at /api-keys — generate, label, and revoke keys
• New: Bearer token authentication (tp_live_-prefixed 56-character keys)
• New: Idempotency-Key header support on POST endpoints
• New: This developer documentation