FRAGMENT

Billing Reference

C Invoices#

a. Create

#

Creates a new invoice

POST /invoices
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.invoices.create(
  {
      invoice_id: 'invoice_2024_001',
      line_items: [
        {
          amount: '1000',
          currency_code: 'USD',
          description: 'Professional services for January 2026',
          product_id: 'prod_1234567890',
          type: 'payout',
          user: { id: 'user_abc123' }
        }
      ]
    }
);
Parameters
invoice_id
string, required
Unique identifier for the invoice. Make this the canonical ID from your system for the transaction.
line_items
object[], required
List of line items to create with the invoice
tags
object[]
Optional metadata tags for this invoice
Response
{
  "data": {
    "id": "inv_1234567890",
    "workspace_id": "ws_1234567890",
    "created": "2024-01-13T00:00:00Z",
    "modified": "2024-01-13T00:00:00Z",
    "version": 1,
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ]
  }
}

b. List

#

Lists all invoices for the workspace

GET /invoices
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.invoices.list();
Response
{
  "data": [
    {
      "id": "inv_1234567890",
      "workspace_id": "ws_1234567890",
      "created": "2024-01-13T00:00:00Z",
      "modified": "2024-01-13T00:00:00Z",
      "version": 1,
      "tags": [
        {
          "key": "region",
          "value": "us-east"
        }
      ]
    }
  ]
}

c. List History

#

Gets the version history of an invoice

GET /invoices/{id}/history
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.invoices.listHistory('inv_1234567890');
Parameters
id
string, required
Invoice ID
Response
{
  "data": [
    {
      "id": "inv_1234567890",
      "workspace_id": "ws_1234567890",
      "created": "2024-01-13T00:00:00Z",
      "modified": "2024-01-13T00:00:00Z",
      "version": 1,
      "tags": [
        {
          "key": "region",
          "value": "us-east"
        }
      ]
    }
  ]
}

d. Retrieve

#

Gets an invoice by ID with balance details

GET /invoices/{id}
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.invoices.retrieve('inv_1234567890');
Parameters
id
string, required
Invoice ID
Response
{
  "data": {
    "id": "inv_1234567890",
    "workspace_id": "ws_1234567890",
    "created": "2024-01-13T00:00:00Z",
    "modified": "2024-01-13T00:00:00Z",
    "version": 1,
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ],
    "users": [
      {
        "id": "user_ext_789",
        "balances": []
      }
    ],
    "balances": [
      {
        "payins": {
          "expected": "10000",
          "actual": "5000",
          "remaining": "5000"
        },
        "payouts": {
          "expected": "10000",
          "actual": "5000",
          "remaining": "5000"
        },
        "net": {
          "expected": "10000",
          "actual": "5000",
          "remaining": "5000"
        },
        "currency": "USD"
      }
    ],
    "payments": [
      {
        "amount": "150",
        "currency": "USD",
        "transaction": {
          "id": "txn_dHhuX2ZyYWdfMDAx",
          "external_id": "bank_txn_123",
          "tags": [
            {}
          ]
        },
        "type": "payin",
        "posted": "2026-02-12T00:00:00.000Z",
        "user": {
          "id": "user_abc123",
          "external_id": "user-ext-001"
        }
      }
    ]
  }
}

e. Update

#

Updates an invoice

PATCH /invoices/{id}
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.invoices.update(
  'inv_1234567890',
  {
      current_invoice_version: 3,
      line_items: {
        update: [
          {
            id: 'li_1234567890',
            price: { amount: '2000' }
          }
        ]
      },
      tags: { update: [{ key: 'region', value: 'eu-west-1' }] }
    }
);
Parameters
id
string, required
Invoice ID
current_invoice_version
number, required
The current version of the invoice. Must match the stored version for the update to succeed (optimistic concurrency).
tags
object
line_items
object
Response
{
  "data": {
    "id": "inv_1234567890",
    "workspace_id": "ws_1234567890",
    "created": "2024-01-13T00:00:00Z",
    "modified": "2024-01-13T00:00:00Z",
    "version": 1,
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ]
  }
}

f. Search

#

Searches invoices

POST /invoices/search
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.invoices.search(
  {
      filter: { status: 'open' },
      page_info: { limit: 20 }
    }
);
Parameters
filter
object, required
Filter criteria for the search
page_info
object, required
Pagination parameters
Response
{
  "data": {
    "invoices": [
      {
        "id": "inv_1234567890",
        "workspace_id": "ws_1234567890",
        "created": "2024-01-13T00:00:00Z",
        "modified": "2024-01-13T00:00:00Z",
        "version": 1,
        "tags": [
          {}
        ],
        "users": [
          {}
        ],
        "balances": [],
        "payments": [
          {}
        ]
      }
    ],
    "page_info": {}
  }
}
©
 FRAGMENT  
2026
○ Light
○ Dark
● System