Skip to content
FRAGMENT
API Reference
Invoices

Update

PATCH/invoices/{id}

Updates an invoice

Path ParametersExpand Collapse
id: string

Invoice ID

Body ParametersJSONExpand Collapse
current_invoice_version: number

The current version of the invoice. Must match the stored version for the update to succeed (optimistic concurrency).

line_items: optional object { create, delete, update }
create: optional array of object { description, product_id, type, 5 more }

Line items to add to the invoice

description: string

Description of the line item

product_id: string

ID of the product/catalog item

type: "payin" or "payout"

The type of the line item

Accepts one of the following:
"payin"
"payout"
user: object { id } or object { external_id }

Identifies a user by Fragment-generated id or external_id (request body).

Accepts one of the following:
ID = object { id }
id: string

FRAGMENT generated ID of the user

ExternalID = object { external_id }
external_id: string

External ID of the user

Deprecatedamount: optional string

Deprecated: use price instead. Total amount in smallest currency unit.

currency_code: optional "ADA" or "BTC" or "DAI" or 176 more

Currency code (ISO 4217 or crypto)

Accepts one of the following:
"ADA"
"BTC"
"DAI"
"ETH"
"SOL"
"USDC"
"USDT"
"USDG"
"EURC"
"CADC"
"CADT"
"XLM"
"UNI"
"BCH"
"LTC"
"AAVE"
"LINK"
"MATIC"
"PTS"
"AED"
"AFN"
"ALL"
"AMD"
"ANG"
"AOA"
"ARS"
"AUD"
"AWG"
"AZN"
"BAM"
"BBD"
"BDT"
"BGN"
"BHD"
"BIF"
"BMD"
"BND"
"BOB"
"BRL"
"BSD"
"BTN"
"BWP"
"BYR"
"BZD"
"CAD"
"CDF"
"CHF"
"CLP"
"CNY"
"COP"
"CRC"
"CUC"
"CUP"
"CVE"
"CZK"
"DJF"
"DKK"
"DOP"
"DZD"
"EGP"
"ERN"
"ETB"
"EUR"
"FJD"
"FKP"
"GBP"
"GEL"
"GGP"
"GHS"
"GIP"
"GMD"
"GNF"
"GTQ"
"GYD"
"HKD"
"HNL"
"HRK"
"HTG"
"HUF"
"IDR"
"ILS"
"IMP"
"INR"
"IQD"
"IRR"
"ISK"
"JMD"
"JOD"
"JPY"
"KES"
"KGS"
"KHR"
"KMF"
"KPW"
"KRW"
"KWD"
"KYD"
"KZT"
"LAK"
"LBP"
"LKR"
"LRD"
"LSL"
"LYD"
"MAD"
"MDL"
"MGA"
"MKD"
"MMK"
"MNT"
"MOP"
"MUR"
"MVR"
"MWK"
"MXN"
"MYR"
"MZN"
"NAD"
"NGN"
"NIO"
"NOK"
"NPR"
"NZD"
"OMR"
"PAB"
"PEN"
"PGK"
"PHP"
"PKR"
"PLN"
"PYG"
"QAR"
"RON"
"RSD"
"RUB"
"RWF"
"SAR"
"SBD"
"SCR"
"SDG"
"SEK"
"SGD"
"SHP"
"SLL"
"SOS"
"SPL"
"SRD"
"SVC"
"SYP"
"STN"
"SZL"
"THB"
"TJS"
"TMT"
"TND"
"TOP"
"TRY"
"TTD"
"TVD"
"TWD"
"TZS"
"UAH"
"UGX"
"USD"
"UYU"
"UZS"
"VEF"
"VND"
"VUV"
"WST"
"XAF"
"XCD"
"XOF"
"XPF"
"YER"
"ZAR"
"ZMW"
"LOGICAL"
"CUSTOM"
price: optional object { amount, quantity, unit_price }

Price breakdown. Provide amount, or unit_price + quantity, or all three.

amount: optional string

Total amount in smallest currency unit. Required if unit_price and quantity are not provided.

quantity: optional number

Number of units for this line item.

minimum1
unit_price: optional string

Price per unit in smallest currency unit.

tags: optional array of object { key, value }

Optional metadata tags for this line item

key: string

Tag key. Must be a valid safe string (no special characters like #, /, :). Max 50 characters.

value: string

Tag value. Must be a valid safe string (no special characters like #, /, :). Max 200 characters.

delete: optional array of object { id }

Line items to remove from the invoice

id: string

ID of the line item to delete

update: optional array of object { id, description, price, tags }

Existing line items to update

id: string

ID of the line item to update

description: optional string
price: optional object { quantity, unit_price, amount }
quantity: number

Number of units for this line item.

minimum1
unit_price: string

Price per unit in smallest currency unit.

amount: optional string

Total amount in smallest currency unit.

tags: optional object { create, delete, set, update }
create: optional array of object { key, value }

Tags to add. Prefer set unless you specifically want create-only validation.

key: string

Tag key. Must be a valid safe string (no special characters like #, /, :). Max 50 characters.

value: string

Tag value. Must be a valid safe string (no special characters like #, /, :). Max 200 characters.

delete: optional array of object { key }

Tags to remove by key

key: string

Tag key to delete

set: optional array of object { key, value }

Tags to create or overwrite without requiring the caller to distinguish between create and update.

key: string

Tag key. Must be a valid safe string (no special characters like #, /, :). Max 50 characters.

value: string

Tag value. Must be a valid safe string (no special characters like #, /, :). Max 200 characters.

update: optional array of object { key, value }

Tags to update. The key identifies the existing tag; the value is the new value. Prefer set unless you specifically want update-only validation.

key: string

Tag key. Must be a valid safe string (no special characters like #, /, :). Max 50 characters.

value: string

Tag value. Must be a valid safe string (no special characters like #, /, :). Max 200 characters.

tags: optional object { create, delete, set, update }
create: optional array of object { key, value }

Tags to add. Prefer set unless you specifically want create-only validation.

key: string

Tag key. Must be a valid safe string (no special characters like #, /, :). Max 50 characters.

value: string

Tag value. Must be a valid safe string (no special characters like #, /, :). Max 200 characters.

delete: optional array of object { key }

Tags to remove by key

key: string

Tag key to delete

set: optional array of object { key, value }

Tags to create or overwrite without requiring the caller to distinguish between create and update.

key: string

Tag key. Must be a valid safe string (no special characters like #, /, :). Max 50 characters.

value: string

Tag value. Must be a valid safe string (no special characters like #, /, :). Max 200 characters.

update: optional array of object { key, value }

Tags to update. The key identifies the existing tag; the value is the new value. Prefer set unless you specifically want update-only validation.

key: string

Tag key. Must be a valid safe string (no special characters like #, /, :). Max 50 characters.

value: string

Tag value. Must be a valid safe string (no special characters like #, /, :). Max 200 characters.

ReturnsExpand Collapse
data: Invoice { id, created, status, 5 more }

Invoice object

id: string

Unique identifier for the invoice

created: string

ISO 8601 timestamp when the invoice was created

formatdate-time
Deprecatedstatus: "active"

Deprecated: The status of the invoice

tags: array of object { key, value }

Metadata tags for this invoice

key: string

Tag key

value: string

Tag value

version: number

The current version of the invoice. Pass this value when updating to ensure thread safety.

workspace_id: string

Workspace ID this invoice belongs to

line_items: optional array of object { id, amount, currency_code, 6 more }

List of line items associated with this invoice

id: string

Unique identifier for the line item

Deprecatedamount: string

Deprecated: use price.amount instead. Total amount in smallest currency unit (represented as string for bigint)

currency_code: "ADA" or "BTC" or "DAI" or 176 more

Currency code (ISO 4217 or crypto)

Accepts one of the following:
"ADA"
"BTC"
"DAI"
"ETH"
"SOL"
"USDC"
"USDT"
"USDG"
"EURC"
"CADC"
"CADT"
"XLM"
"UNI"
"BCH"
"LTC"
"AAVE"
"LINK"
"MATIC"
"PTS"
"AED"
"AFN"
"ALL"
"AMD"
"ANG"
"AOA"
"ARS"
"AUD"
"AWG"
"AZN"
"BAM"
"BBD"
"BDT"
"BGN"
"BHD"
"BIF"
"BMD"
"BND"
"BOB"
"BRL"
"BSD"
"BTN"
"BWP"
"BYR"
"BZD"
"CAD"
"CDF"
"CHF"
"CLP"
"CNY"
"COP"
"CRC"
"CUC"
"CUP"
"CVE"
"CZK"
"DJF"
"DKK"
"DOP"
"DZD"
"EGP"
"ERN"
"ETB"
"EUR"
"FJD"
"FKP"
"GBP"
"GEL"
"GGP"
"GHS"
"GIP"
"GMD"
"GNF"
"GTQ"
"GYD"
"HKD"
"HNL"
"HRK"
"HTG"
"HUF"
"IDR"
"ILS"
"IMP"
"INR"
"IQD"
"IRR"
"ISK"
"JMD"
"JOD"
"JPY"
"KES"
"KGS"
"KHR"
"KMF"
"KPW"
"KRW"
"KWD"
"KYD"
"KZT"
"LAK"
"LBP"
"LKR"
"LRD"
"LSL"
"LYD"
"MAD"
"MDL"
"MGA"
"MKD"
"MMK"
"MNT"
"MOP"
"MUR"
"MVR"
"MWK"
"MXN"
"MYR"
"MZN"
"NAD"
"NGN"
"NIO"
"NOK"
"NPR"
"NZD"
"OMR"
"PAB"
"PEN"
"PGK"
"PHP"
"PKR"
"PLN"
"PYG"
"QAR"
"RON"
"RSD"
"RUB"
"RWF"
"SAR"
"SBD"
"SCR"
"SDG"
"SEK"
"SGD"
"SHP"
"SLL"
"SOS"
"SPL"
"SRD"
"SVC"
"SYP"
"STN"
"SZL"
"THB"
"TJS"
"TMT"
"TND"
"TOP"
"TRY"
"TTD"
"TVD"
"TWD"
"TZS"
"UAH"
"UGX"
"USD"
"UYU"
"UZS"
"VEF"
"VND"
"VUV"
"WST"
"XAF"
"XCD"
"XOF"
"XPF"
"YER"
"ZAR"
"ZMW"
"LOGICAL"
"CUSTOM"
description: string

Description of the line item

price: object { amount, quantity, unit_price }

Price breakdown containing amount, unit price, and quantity

amount: string

Total amount in smallest currency unit (represented as string for bigint)

quantity: number

Quantity of units for this line item

unit_price: string

Unit price in smallest currency unit (represented as string for bigint)

product_id: string

ID of the product/catalog item

tags: array of object { key, value }

Metadata tags for this line item

key: string

Tag key

value: string

Tag value

type: "payin" or "payout"

The type of the line item

Accepts one of the following:
"payin"
"payout"
user_id: string

External ID of the user associated with this line item

modified: optional string

ISO 8601 timestamp when the invoice was last modified

formatdate-time

Update

curl https://api.us-west-2.fragment.dev/invoices/$ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -d '{
          "current_invoice_version": 3,
          "line_items": {
            "update": [
              {
                "id": "li_1234567890",
                "price": {
                  "quantity": 2,
                  "unit_price": "500",
                  "amount": "2000"
                }
              }
            ]
          },
          "tags": {
            "set": [
              {
                "key": "region",
                "value": "eu-west-1"
              }
            ]
          }
        }'
{
  "data": {
    "id": "inv_1234567890",
    "created": "2024-01-13T00:00:00Z",
    "status": "active",
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ],
    "version": 1,
    "workspace_id": "ws_1234567890",
    "line_items": [
      {
        "id": "item_1234567890",
        "amount": "1000",
        "currency_code": "USD",
        "description": "Professional services for January 2026",
        "price": {
          "amount": "1000",
          "quantity": 1,
          "unit_price": "1000"
        },
        "product_id": "prod_1234567890",
        "tags": [
          {
            "key": "region",
            "value": "us-east"
          }
        ],
        "type": "payout",
        "user_id": "user_ext_456"
      }
    ],
    "modified": "2024-01-13T00:00:00Z"
  }
}
Returns Examples
{
  "data": {
    "id": "inv_1234567890",
    "created": "2024-01-13T00:00:00Z",
    "status": "active",
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ],
    "version": 1,
    "workspace_id": "ws_1234567890",
    "line_items": [
      {
        "id": "item_1234567890",
        "amount": "1000",
        "currency_code": "USD",
        "description": "Professional services for January 2026",
        "price": {
          "amount": "1000",
          "quantity": 1,
          "unit_price": "1000"
        },
        "product_id": "prod_1234567890",
        "tags": [
          {
            "key": "region",
            "value": "us-east"
          }
        ],
        "type": "payout",
        "user_id": "user_ext_456"
      }
    ],
    "modified": "2024-01-13T00:00:00Z"
  }
}