Create ledger entry by external ID

curl --request POST \
  --url https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/ledger_entry \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entry_type": "increment",
  "amount": 123,
  "metadata": {},
  "currency": "<string>",
  "description": "<string>",
  "expiry_date": "2023-12-25",
  "effective_date": "2023-12-25",
  "per_unit_cost_basis": "<string>",
  "invoice_settings": {
    "auto_collection": true,
    "net_terms": 123,
    "memo": "<string>",
    "require_successful_payment": false,
    "invoice_date": "2023-12-25",
    "custom_due_date": "2023-12-25",
    "item_id": "<string>"
  },
  "filters": [
    {
      "field": "item_id",
      "operator": "includes",
      "values": [
        "<string>"
      ]
    }
  ]
}
'

{
  "metadata": {},
  "id": "<string>",
  "ledger_sequence_number": 123,
  "entry_status": "committed",
  "customer": {
    "id": "<string>",
    "external_customer_id": "<string>"
  },
  "starting_balance": 123,
  "ending_balance": 123,
  "amount": 123,
  "currency": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "credit_block": {
    "id": "<string>",
    "expiry_date": "2023-11-07T05:31:56Z",
    "per_unit_cost_basis": "<string>",
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<string>"
        ]
      }
    ]
  },
  "entry_type": "increment",
  "created_invoices": [
    {
      "metadata": {},
      "voided_at": "2023-11-07T05:31:56Z",
      "paid_at": "2023-11-07T05:31:56Z",
      "issued_at": "2023-11-07T05:31:56Z",
      "scheduled_issue_at": "2023-11-07T05:31:56Z",
      "auto_collection": {
        "next_attempt_at": "2023-11-07T05:31:56Z",
        "previously_attempted_at": "2023-11-07T05:31:56Z",
        "enabled": true,
        "num_attempts": 123
      },
      "issue_failed_at": "2023-11-07T05:31:56Z",
      "sync_failed_at": "2023-11-07T05:31:56Z",
      "payment_failed_at": "2023-11-07T05:31:56Z",
      "payment_started_at": "2023-11-07T05:31:56Z",
      "amount_due": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "customer": {
        "id": "<string>",
        "external_customer_id": "<string>"
      },
      "due_date": "2022-05-30T07:00:00+00:00",
      "id": "<string>",
      "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
      "invoice_number": "<string>",
      "subscription": {
        "id": "<string>"
      },
      "total": "<string>",
      "customer_balance_transactions": [
        {
          "id": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "starting_balance": "<string>",
          "ending_balance": "<string>",
          "amount": "<string>",
          "action": "applied_to_invoice",
          "description": "An optional description",
          "invoice": {
            "id": "<string>"
          },
          "type": "increment",
          "credit_note": {
            "id": "<string>"
          }
        }
      ],
      "status": "issued",
      "invoice_source": "subscription",
      "shipping_address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
      },
      "billing_address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
      },
      "hosted_invoice_url": "<string>",
      "will_auto_issue": true,
      "eligible_to_issue_at": "2023-11-07T05:31:56Z",
      "customer_tax_id": {
        "country": "AD",
        "type": "ad_nrt",
        "value": "<string>"
      },
      "memo": "<string>",
      "credit_notes": [
        {
          "id": "<string>",
          "credit_note_number": "<string>",
          "reason": "<string>",
          "total": "<string>",
          "voided_at": "2022-05-01T07:01:31+00:00",
          "type": "<string>",
          "memo": "<string>"
        }
      ],
      "payment_attempts": [
        {
          "id": "<string>",
          "payment_provider": "stripe",
          "payment_provider_id": "<string>",
          "amount": "<string>",
          "succeeded": true,
          "created_at": "2023-11-07T05:31:56Z",
          "receipt_pdf": "https://assets.withorb.com/receipt/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"
        }
      ],
      "discount": "<unknown>",
      "discounts": [
        {
          "discount_type": "percentage",
          "percentage_discount": 0.5,
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<string>"
        }
      ],
      "minimum": {
        "minimum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "minimum_amount": "<string>",
      "maximum": {
        "maximum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "maximum_amount": "<string>",
      "line_items": [
        {
          "amount": "<string>",
          "end_date": "2023-11-07T05:31:56Z",
          "grouping": "<string>",
          "adjustments": [
            {
              "id": "<string>",
              "is_invoice_level": true,
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "applies_to_price_ids": [
                "<string>"
              ],
              "reason": "<string>",
              "replaces_adjustment_id": "<string>",
              "adjustment_type": "usage_discount",
              "usage_discount": 123,
              "amount": "<string>"
            }
          ],
          "name": "<string>",
          "quantity": 123,
          "start_date": "2023-11-07T05:31:56Z",
          "subtotal": "<string>",
          "adjusted_subtotal": "<string>",
          "credits_applied": "<string>",
          "partially_invoiced_amount": "<string>",
          "sub_line_items": [
            {
              "amount": "<string>",
              "name": "<string>",
              "quantity": 123,
              "grouping": {
                "key": "<string>",
                "value": "west"
              },
              "type": "matrix",
              "matrix_config": {
                "dimension_values": [
                  "<string>"
                ]
              },
              "scaled_quantity": 123
            }
          ],
          "tax_amounts": [
            {
              "tax_rate_description": "<string>",
              "tax_rate_percentage": "<string>",
              "amount": "<string>"
            }
          ],
          "id": "<string>",
          "price": {
            "model_type": "unit",
            "unit_config": {
              "unit_amount": "<string>",
              "prorated": false
            },
            "metadata": {},
            "id": "<string>",
            "name": "<string>",
            "external_price_id": "<string>",
            "replaces_price_id": "<string>",
            "price_type": "usage_price",
            "created_at": "2023-11-07T05:31:56Z",
            "cadence": "one_time",
            "billing_mode": "in_advance",
            "billing_cycle_configuration": {
              "duration": 123,
              "duration_unit": "day"
            },
            "invoicing_cycle_configuration": {
              "duration": 123,
              "duration_unit": "day"
            },
            "billable_metric": {
              "id": "<string>"
            },
            "fixed_price_quantity": 123,
            "plan_phase_order": 123,
            "currency": "<string>",
            "conversion_rate": 123,
            "conversion_rate_config": {
              "conversion_rate_type": "unit",
              "unit_config": {
                "unit_amount": "<string>"
              }
            },
            "item": {
              "id": "<string>",
              "name": "<string>"
            },
            "credit_allocation": {
              "currency": "<string>",
              "allows_rollover": true,
              "custom_expiration": {
                "duration": 123,
                "duration_unit": "day"
              },
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ]
            },
            "composite_price_filters": [
              {
                "field": "price_id",
                "operator": "includes",
                "values": [
                  "<string>"
                ]
              }
            ],
            "discount": {
              "discount_type": "percentage",
              "percentage_discount": 0.5,
              "applies_to_price_ids": [
                "h74gfhdjvn7ujokd",
                "7hfgtgjnbvc3ujkl"
              ],
              "filters": "<unknown>",
              "reason": "<unknown>"
            },
            "minimum": {
              "minimum_amount": "<string>",
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "applies_to_price_ids": [
                "<string>"
              ]
            },
            "minimum_amount": "<string>",
            "maximum": {
              "maximum_amount": "<string>",
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "applies_to_price_ids": [
                "<string>"
              ]
            },
            "maximum_amount": "<string>",
            "dimensional_price_configuration": {
              "dimensional_price_group_id": "<string>",
              "dimension_values": [
                "<string>"
              ]
            }
          },
          "usage_customer_ids": [
            "<string>"
          ],
          "filter": "<string>"
        }
      ],
      "subtotal": "<string>",
      "invoice_date": "2023-11-07T05:31:56Z"
    }
  ]
}

Credit

Create ledger entry by external ID

This endpoint allows you to create a new ledger entry for a specified customer’s balance. This can be used to increment balance, deduct credits, and change the expiry date of existing credits.

Effects of adding a ledger entry

After calling this endpoint, Fetch Credit Balance will return a credit block that represents the changes (i.e. balance changes or transfers).
A ledger entry will be added to the credits ledger for this customer, and therefore returned in the View Credits Ledger response as well as serialized in the response to this request. In the case of deductions without a specified block, multiple ledger entries may be created if the deduction spans credit blocks.
If invoice_settings is specified, an invoice will be created that reflects the cost of the credits (based on amount and per_unit_cost_basis).

Adding credits

Adding credits is done by creating an entry of type increment. This requires the caller to specify a number of credits as well as an optional expiry date in YYYY-MM-DD format. Orb also recommends specifying a description to assist with auditing. When adding credits, the caller can also specify a cost basis per-credit, to indicate how much in USD a customer paid for a single credit in a block. This can later be used for revenue recognition.

The following snippet illustrates a sample request body to increment credits which will expire in January of 2022.

{
  "entry_type": "increment",
  "amount": 100,
  "expiry_date": "2022-12-28",
  "per_unit_cost_basis": "0.20",
  "description": "Purchased 100 credits"
}

Note that by default, Orb will always first increment any negative balance in existing blocks before adding the remaining amount to the desired credit block.

Invoicing for credits

By default, Orb manipulates the credit ledger but does not charge for credits. However, if you pass invoice_settings in the body of this request, Orb will also generate a one-off invoice for the customer for the credits pre-purchase. Note that you must provide the per_unit_cost_basis, since the total charges on the invoice are calculated by multiplying the cost basis with the number of credit units added.

Deducting Credits

Orb allows you to deduct credits from a customer by creating an entry of type decrement. Orb matches the algorithm for automatic deductions for determining which credit blocks to decrement from. In the case that the deduction leads to multiple ledger entries, the response from this endpoint will be the final deduction. Orb also optionally allows specifying a description to assist with auditing.

The following snippet illustrates a sample request body to decrement credits.

{
  "entry_type": "decrement",
  "amount": 20,
  "description": "Removing excess credits"
}

Changing credits expiry

If you’d like to change when existing credits expire, you should create a ledger entry of type expiration_change. For this entry, the required parameter expiry_date identifies the originating block, and the required parameter target_expiry_date identifies when the transferred credits should now expire. A new credit block will be created with expiry date target_expiry_date, with the same cost basis data as the original credit block, if present.

Note that the balance of the block with the given expiry_date must be at least equal to the desired transfer amount determined by the amount parameter.

The following snippet illustrates a sample request body to extend the expiration date of credits by one year:

{
  "entry_type": "expiration_change",
  "amount": 10,
  "expiry_date": "2022-12-28",
  "block_id": "UiUhFWeLHPrBY4Ad",
  "target_expiry_date": "2023-12-28",
  "description": "Extending credit validity"
}

Voiding credits

If you’d like to void a credit block, create a ledger entry of type void. For this entry, block_id is required to identify the block, and amount indicates how many credits to void, up to the block’s initial balance. Pass in a void_reason of refund if the void is due to a refund.

Amendment

If you’d like to undo a decrement on a credit block, create a ledger entry of type amendment. For this entry, block_id is required to identify the block that was originally decremented from, and amount indicates how many credits to return to the customer, up to the block’s initial balance.

POST

customers

external_customer_id

{external_customer_id}

credits

ledger_entry

Create ledger entry by external ID

curl --request POST \
  --url https://api.withorb.com/v1/customers/external_customer_id/{external_customer_id}/credits/ledger_entry \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entry_type": "increment",
  "amount": 123,
  "metadata": {},
  "currency": "<string>",
  "description": "<string>",
  "expiry_date": "2023-12-25",
  "effective_date": "2023-12-25",
  "per_unit_cost_basis": "<string>",
  "invoice_settings": {
    "auto_collection": true,
    "net_terms": 123,
    "memo": "<string>",
    "require_successful_payment": false,
    "invoice_date": "2023-12-25",
    "custom_due_date": "2023-12-25",
    "item_id": "<string>"
  },
  "filters": [
    {
      "field": "item_id",
      "operator": "includes",
      "values": [
        "<string>"
      ]
    }
  ]
}
'

{
  "metadata": {},
  "id": "<string>",
  "ledger_sequence_number": 123,
  "entry_status": "committed",
  "customer": {
    "id": "<string>",
    "external_customer_id": "<string>"
  },
  "starting_balance": 123,
  "ending_balance": 123,
  "amount": 123,
  "currency": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "credit_block": {
    "id": "<string>",
    "expiry_date": "2023-11-07T05:31:56Z",
    "per_unit_cost_basis": "<string>",
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<string>"
        ]
      }
    ]
  },
  "entry_type": "increment",
  "created_invoices": [
    {
      "metadata": {},
      "voided_at": "2023-11-07T05:31:56Z",
      "paid_at": "2023-11-07T05:31:56Z",
      "issued_at": "2023-11-07T05:31:56Z",
      "scheduled_issue_at": "2023-11-07T05:31:56Z",
      "auto_collection": {
        "next_attempt_at": "2023-11-07T05:31:56Z",
        "previously_attempted_at": "2023-11-07T05:31:56Z",
        "enabled": true,
        "num_attempts": 123
      },
      "issue_failed_at": "2023-11-07T05:31:56Z",
      "sync_failed_at": "2023-11-07T05:31:56Z",
      "payment_failed_at": "2023-11-07T05:31:56Z",
      "payment_started_at": "2023-11-07T05:31:56Z",
      "amount_due": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "customer": {
        "id": "<string>",
        "external_customer_id": "<string>"
      },
      "due_date": "2022-05-30T07:00:00+00:00",
      "id": "<string>",
      "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
      "invoice_number": "<string>",
      "subscription": {
        "id": "<string>"
      },
      "total": "<string>",
      "customer_balance_transactions": [
        {
          "id": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "starting_balance": "<string>",
          "ending_balance": "<string>",
          "amount": "<string>",
          "action": "applied_to_invoice",
          "description": "An optional description",
          "invoice": {
            "id": "<string>"
          },
          "type": "increment",
          "credit_note": {
            "id": "<string>"
          }
        }
      ],
      "status": "issued",
      "invoice_source": "subscription",
      "shipping_address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
      },
      "billing_address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
      },
      "hosted_invoice_url": "<string>",
      "will_auto_issue": true,
      "eligible_to_issue_at": "2023-11-07T05:31:56Z",
      "customer_tax_id": {
        "country": "AD",
        "type": "ad_nrt",
        "value": "<string>"
      },
      "memo": "<string>",
      "credit_notes": [
        {
          "id": "<string>",
          "credit_note_number": "<string>",
          "reason": "<string>",
          "total": "<string>",
          "voided_at": "2022-05-01T07:01:31+00:00",
          "type": "<string>",
          "memo": "<string>"
        }
      ],
      "payment_attempts": [
        {
          "id": "<string>",
          "payment_provider": "stripe",
          "payment_provider_id": "<string>",
          "amount": "<string>",
          "succeeded": true,
          "created_at": "2023-11-07T05:31:56Z",
          "receipt_pdf": "https://assets.withorb.com/receipt/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"
        }
      ],
      "discount": "<unknown>",
      "discounts": [
        {
          "discount_type": "percentage",
          "percentage_discount": 0.5,
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<string>"
        }
      ],
      "minimum": {
        "minimum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "minimum_amount": "<string>",
      "maximum": {
        "maximum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "maximum_amount": "<string>",
      "line_items": [
        {
          "amount": "<string>",
          "end_date": "2023-11-07T05:31:56Z",
          "grouping": "<string>",
          "adjustments": [
            {
              "id": "<string>",
              "is_invoice_level": true,
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "applies_to_price_ids": [
                "<string>"
              ],
              "reason": "<string>",
              "replaces_adjustment_id": "<string>",
              "adjustment_type": "usage_discount",
              "usage_discount": 123,
              "amount": "<string>"
            }
          ],
          "name": "<string>",
          "quantity": 123,
          "start_date": "2023-11-07T05:31:56Z",
          "subtotal": "<string>",
          "adjusted_subtotal": "<string>",
          "credits_applied": "<string>",
          "partially_invoiced_amount": "<string>",
          "sub_line_items": [
            {
              "amount": "<string>",
              "name": "<string>",
              "quantity": 123,
              "grouping": {
                "key": "<string>",
                "value": "west"
              },
              "type": "matrix",
              "matrix_config": {
                "dimension_values": [
                  "<string>"
                ]
              },
              "scaled_quantity": 123
            }
          ],
          "tax_amounts": [
            {
              "tax_rate_description": "<string>",
              "tax_rate_percentage": "<string>",
              "amount": "<string>"
            }
          ],
          "id": "<string>",
          "price": {
            "model_type": "unit",
            "unit_config": {
              "unit_amount": "<string>",
              "prorated": false
            },
            "metadata": {},
            "id": "<string>",
            "name": "<string>",
            "external_price_id": "<string>",
            "replaces_price_id": "<string>",
            "price_type": "usage_price",
            "created_at": "2023-11-07T05:31:56Z",
            "cadence": "one_time",
            "billing_mode": "in_advance",
            "billing_cycle_configuration": {
              "duration": 123,
              "duration_unit": "day"
            },
            "invoicing_cycle_configuration": {
              "duration": 123,
              "duration_unit": "day"
            },
            "billable_metric": {
              "id": "<string>"
            },
            "fixed_price_quantity": 123,
            "plan_phase_order": 123,
            "currency": "<string>",
            "conversion_rate": 123,
            "conversion_rate_config": {
              "conversion_rate_type": "unit",
              "unit_config": {
                "unit_amount": "<string>"
              }
            },
            "item": {
              "id": "<string>",
              "name": "<string>"
            },
            "credit_allocation": {
              "currency": "<string>",
              "allows_rollover": true,
              "custom_expiration": {
                "duration": 123,
                "duration_unit": "day"
              },
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ]
            },
            "composite_price_filters": [
              {
                "field": "price_id",
                "operator": "includes",
                "values": [
                  "<string>"
                ]
              }
            ],
            "discount": {
              "discount_type": "percentage",
              "percentage_discount": 0.5,
              "applies_to_price_ids": [
                "h74gfhdjvn7ujokd",
                "7hfgtgjnbvc3ujkl"
              ],
              "filters": "<unknown>",
              "reason": "<unknown>"
            },
            "minimum": {
              "minimum_amount": "<string>",
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "applies_to_price_ids": [
                "<string>"
              ]
            },
            "minimum_amount": "<string>",
            "maximum": {
              "maximum_amount": "<string>",
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "applies_to_price_ids": [
                "<string>"
              ]
            },
            "maximum_amount": "<string>",
            "dimensional_price_configuration": {
              "dimensional_price_group_id": "<string>",
              "dimension_values": [
                "<string>"
              ]
            }
          },
          "usage_customer_ids": [
            "<string>"
          ],
          "filter": "<string>"
        }
      ],
      "subtotal": "<string>",
      "invoice_date": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

Authorization

string

header

required

API Keys can be issued in the Orb's web application.

Path Parameters

external_customer_id

string | null

required

Body

application/json

AddIncrementCreditLedgerEntryRequestParams
AddDecrementCreditLedgerEntryRequestParams
AddExpirationChangeCreditLedgerEntryRequestParams
AddVoidCreditLedgerEntryRequestParams
AddAmendmentCreditLedgerEntryRequestParams

entry_type

enum<string>

required

Available options:

increment

amount

number

required

The number of credits to effect. Note that this is required for increment, decrement, void, or undo operations.

metadata

Metadata · object

User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

Show child attributes

metadata.{key}

string | null

currency

string | null

The currency or custom pricing unit to use for this ledger entry. If this is a real-world currency, it must match the customer's invoicing currency.

description

string | null

Optional metadata that can be specified when adding ledger results via the API. For example, this can be used to note an increment refers to trial credits, or for noting corrections as a result of an incident, etc.

expiry_date

An ISO 8601 format date that denotes when this credit balance should expire.

effective_date

An ISO 8601 format date that denotes when this credit balance should become available for use.

per_unit_cost_basis

string | null

Can only be specified when entry_type=increment. How much, in the customer's currency, a customer paid for a single credit in this block

invoice_settings

IncrementCreditLedgerEntryInvoiceSettings · object

Passing invoice_settings automatically generates an invoice for the newly added credits. If invoice_settings is passed, you must specify per_unit_cost_basis, as the calculation of the invoice total is done on that basis.

Show child attributes

invoice_settings.auto_collection

boolean

required

Whether the credits purchase invoice should auto collect with the customer's saved payment method.

invoice_settings.net_terms

integer | null

The net terms determines the due date of the invoice. Due date is calculated based on the invoice or issuance date, depending on the account's configured due date calculation method. A value of '0' here represents that the invoice is due on issue, whereas a value of '30' represents that the customer has 30 days to pay the invoice. Do not set this field if you want to set a custom due date.

invoice_settings.memo

string | null

An optional memo to display on the invoice.

invoice_settings.require_successful_payment

boolean

default:false

If true, the new credit block will require that the corresponding invoice is paid before it can be drawn down from.

invoice_settings.invoice_date

An ISO 8601 format date that denotes when this invoice should be dated in the customer's timezone. If not provided, the invoice date will default to the credit block's effective date.

invoice_settings.custom_due_date

An optional custom due date for the invoice. If not set, the due date will be calculated based on the net_terms value.

invoice_settings.item_id

string | null

The ID of the Item to be used for the invoice line item. If not provided, a default 'Credits' item will be used.

filters

BlockPriceFilter · object[] | null

Optional filter to specify which items this credit block applies to. If not specified, the block will apply to all items for the pricing unit.

Show child attributes

filters.field

enum<string>

required

The property of the price the block applies to. Only item_id is supported.

Available options:

item_id

filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

filters.values

string[]

required

The IDs or values that match this filter.

Response

Created

IncrementLedgerEntry
DecrementLedgerEntry
ExpirationChangeLedgerEntry
CreditBlockExpiryLedgerEntry
VoidLedgerEntry
VoidInitiatedLedgerEntry
AmendmentLedgerEntry

The Credit Ledger Entry resource models prepaid credits within Orb.

metadata

Metadata · object

required

User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

Show child attributes

metadata.{key}

string

required

ledger_sequence_number

integer

required

entry_status

enum<string>

required

Available options:

committed,

pending

customer

CustomerMinified · object

required

Show child attributes

customer.id

string

required

customer.external_customer_id

string | null

required

starting_balance

number

required

ending_balance

number

required

amount

number

required

currency

string

required

created_at

string<date-time>

required

description

string | null

required

credit_block

AffectedBlock · object

required

Show child attributes

credit_block.id

string

required

credit_block.expiry_date

string<date-time> | null

required

credit_block.per_unit_cost_basis

string | null

required

credit_block.filters

PriceFilter · object[]

required

Show child attributes

credit_block.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

credit_block.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

credit_block.filters.values

string[]

required

The IDs or values that match this filter.

entry_type

enum<string>

required

Available options:

increment

created_invoices

Invoice · object[] | null

If the increment resulted in invoice creation, the list of created invoices

Show child attributes

created_invoices.metadata

Metadata · object

required

Show child attributes

created_invoices.metadata.{key}

string

created_invoices.voided_at

string<date-time> | null

required

If the invoice has a status of void, this gives a timestamp when the invoice was voided.

created_invoices.paid_at

string<date-time> | null

required

If the invoice has a status of paid, this gives a timestamp when the invoice was paid.

created_invoices.issued_at

string<date-time> | null

required

If the invoice has been issued, this will be the time it transitioned to issued (even if it is now in a different state.)

created_invoices.scheduled_issue_at

string<date-time> | null

required

If the invoice is in draft, this timestamp will reflect when the invoice is scheduled to be issued.

created_invoices.auto_collection

AutoCollection · object

required

Show child attributes

created_invoices.auto_collection.next_attempt_at

string<date-time> | null

required

If the invoice is scheduled for auto-collection, this field will reflect when the next attempt will occur. If dunning has been exhausted, or auto-collection is not enabled for this invoice, this field will be null.

created_invoices.auto_collection.previously_attempted_at

string<date-time> | null

required

If Orb has ever attempted payment auto-collection for this invoice, this field will reflect when that attempt occurred. In conjunction with next_attempt_at, this can be used to tell whether the invoice is currently in dunning (that is, previously_attempted_at is non-null, and next_attempt_time is non-null), or if dunning has been exhausted (previously_attempted_at is non-null, but next_attempt_time is null).

created_invoices.auto_collection.enabled

boolean | null

required

True only if auto-collection is enabled for this invoice.

created_invoices.auto_collection.num_attempts

integer | null

required

Number of auto-collection payment attempts.

created_invoices.issue_failed_at

string<date-time> | null

required

If the invoice failed to issue, this will be the last time it failed to issue (even if it is now in a different state.)

created_invoices.sync_failed_at

string<date-time> | null

required

If the invoice failed to sync, this will be the last time an external invoicing provider sync was attempted. This field will always be null for invoices using Orb Invoicing.

created_invoices.payment_failed_at

string<date-time> | null

required

If payment was attempted on this invoice but failed, this will be the time of the most recent attempt.

created_invoices.payment_started_at

string<date-time> | null

required

If payment was attempted on this invoice, this will be the start time of the most recent attempt. This field is especially useful for delayed-notification payment mechanisms (like bank transfers), where payment can take 3 days or more.

created_invoices.amount_due

string

required

This is the final amount required to be charged to the customer and reflects the application of the customer balance to the total of the invoice.

created_invoices.created_at

string<date-time>

required

The creation time of the resource in Orb.

created_invoices.currency

string

required

An ISO 4217 currency string or credits

created_invoices.customer

CustomerMinified · object

required

Show child attributes

created_invoices.customer.id

string

required

created_invoices.customer.external_customer_id

string | null

required

created_invoices.due_date

string<date-time> | null

required

When the invoice payment is due. The due date is null if the invoice is not yet finalized.

Example:

"2022-05-30T07:00:00+00:00"

created_invoices.id

string

required

created_invoices.invoice_pdf

string | null

required

The link to download the PDF representation of the Invoice.

Example:

"https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"

created_invoices.invoice_number

string

required

Automatically generated invoice number to help track and reconcile invoices. Invoice numbers have a prefix such as RFOBWG. These can be sequential per account or customer.

created_invoices.subscription

SubscriptionMinified · object

required

Show child attributes

created_invoices.subscription.id

string

required

created_invoices.total

string

required

The total after any minimums and discounts have been applied.

created_invoices.customer_balance_transactions

CustomerBalanceTransaction · object[]

required

Show child attributes

created_invoices.customer_balance_transactions.id

string

required

A unique id for this transaction.

created_invoices.customer_balance_transactions.created_at

string<date-time>

required

The creation time of this transaction.

created_invoices.customer_balance_transactions.starting_balance

string

required

The original value of the customer's balance prior to the transaction, in the customer's currency.

created_invoices.customer_balance_transactions.ending_balance

string

required

The new value of the customer's balance prior to the transaction, in the customer's currency.

created_invoices.customer_balance_transactions.amount

string

required

The value of the amount changed in the transaction.

created_invoices.customer_balance_transactions.action

enum<string>

required

Available options:

applied_to_invoice,

manual_adjustment,

prorated_refund,

revert_prorated_refund,

return_from_voiding,

credit_note_applied,

credit_note_voided,

overpayment_refund,

external_payment,

small_invoice_carryover

created_invoices.customer_balance_transactions.description

string | null

required

An optional description provided for manual customer balance adjustments.

Example:

"An optional description"

created_invoices.customer_balance_transactions.invoice

InvoiceTiny · object

required

Show child attributes

created_invoices.customer_balance_transactions.invoice.id

string

required

The Invoice id

created_invoices.customer_balance_transactions.type

enum<string>

required

Available options:

increment,

decrement

created_invoices.customer_balance_transactions.credit_note

CreditNoteTiny · object

required

Show child attributes

created_invoices.customer_balance_transactions.credit_note.id

string

required

The id of the Credit note

created_invoices.status

enum<string>

required

Available options:

issued,

paid,

synced,

void,

draft

created_invoices.invoice_source

enum<string>

required

Available options:

subscription,

partial,

one_off

created_invoices.shipping_address

Address · object

required

Show child attributes

created_invoices.shipping_address.line1

string | null

required

created_invoices.shipping_address.line2

string | null

required

created_invoices.shipping_address.city

string | null

required

created_invoices.shipping_address.state

string | null

required

created_invoices.shipping_address.postal_code

string | null

required

created_invoices.shipping_address.country

string | null

required

created_invoices.billing_address

Address · object

required

Show child attributes

created_invoices.billing_address.line1

string | null

required

created_invoices.billing_address.line2

string | null

required

created_invoices.billing_address.city

string | null

required

created_invoices.billing_address.state

string | null

required

created_invoices.billing_address.postal_code

string | null

required

created_invoices.billing_address.country

string | null

required

created_invoices.hosted_invoice_url

string | null

required

A URL for the customer-facing invoice portal. This URL expires 30 days after the invoice's due date, or 60 days after being re-generated through the UI.

created_invoices.will_auto_issue

boolean

required

This is true if the invoice will be automatically issued in the future, and false otherwise.

created_invoices.eligible_to_issue_at

string<date-time> | null

required

If the invoice has a status of draft, this will be the time that the invoice will be eligible to be issued, otherwise it will be null. If auto-issue is true, the invoice will automatically begin issuing at this time.

created_invoices.customer_tax_id

CustomerTaxId · object

required

Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.

Supported Tax ID Countries and Types

Country	Type	Description
Albania	`al_tin`	Albania Tax Identification Number
Andorra	`ad_nrt`	Andorran NRT Number
Angola	`ao_tin`	Angola Tax Identification Number
Argentina	`ar_cuit`	Argentinian Tax ID Number
Armenia	`am_tin`	Armenia Tax Identification Number
Aruba	`aw_tin`	Aruba Tax Identification Number
Australia	`au_abn`	Australian Business Number (AU ABN)
Australia	`au_arn`	Australian Taxation Office Reference Number
Austria	`eu_vat`	European VAT Number
Azerbaijan	`az_tin`	Azerbaijan Tax Identification Number
Bahamas	`bs_tin`	Bahamas Tax Identification Number
Bahrain	`bh_vat`	Bahraini VAT Number
Bangladesh	`bd_bin`	Bangladesh Business Identification Number
Barbados	`bb_tin`	Barbados Tax Identification Number
Belarus	`by_tin`	Belarus TIN Number
Belgium	`eu_vat`	European VAT Number
Benin	`bj_ifu`	Benin Tax Identification Number (Identifiant Fiscal Unique)
Bolivia	`bo_tin`	Bolivian Tax ID
Bosnia and Herzegovina	`ba_tin`	Bosnia and Herzegovina Tax Identification Number
Brazil	`br_cnpj`	Brazilian CNPJ Number
Brazil	`br_cpf`	Brazilian CPF Number
Bulgaria	`bg_uic`	Bulgaria Unified Identification Code
Bulgaria	`eu_vat`	European VAT Number
Burkina Faso	`bf_ifu`	Burkina Faso Tax Identification Number (Numéro d'Identifiant Fiscal Unique)
Cambodia	`kh_tin`	Cambodia Tax Identification Number
Cameroon	`cm_niu`	Cameroon Tax Identification Number (Numéro d'Identifiant fiscal Unique)
Canada	`ca_bn`	Canadian BN
Canada	`ca_gst_hst`	Canadian GST/HST Number
Canada	`ca_pst_bc`	Canadian PST Number (British Columbia)
Canada	`ca_pst_mb`	Canadian PST Number (Manitoba)
Canada	`ca_pst_sk`	Canadian PST Number (Saskatchewan)
Canada	`ca_qst`	Canadian QST Number (Québec)
Cape Verde	`cv_nif`	Cape Verde Tax Identification Number (Número de Identificação Fiscal)
Chile	`cl_tin`	Chilean TIN
China	`cn_tin`	Chinese Tax ID
Colombia	`co_nit`	Colombian NIT Number
Congo-Kinshasa	`cd_nif`	Congo (DR) Tax Identification Number (Número de Identificação Fiscal)
Costa Rica	`cr_tin`	Costa Rican Tax ID
Croatia	`eu_vat`	European VAT Number
Croatia	`hr_oib`	Croatian Personal Identification Number (OIB)
Cyprus	`eu_vat`	European VAT Number
Czech Republic	`eu_vat`	European VAT Number
Denmark	`eu_vat`	European VAT Number
Dominican Republic	`do_rcn`	Dominican RCN Number
Ecuador	`ec_ruc`	Ecuadorian RUC Number
Egypt	`eg_tin`	Egyptian Tax Identification Number
El Salvador	`sv_nit`	El Salvadorian NIT Number
Estonia	`eu_vat`	European VAT Number
Ethiopia	`et_tin`	Ethiopia Tax Identification Number
European Union	`eu_oss_vat`	European One Stop Shop VAT Number for non-Union scheme
Finland	`eu_vat`	European VAT Number
France	`eu_vat`	European VAT Number
Georgia	`ge_vat`	Georgian VAT
Germany	`de_stn`	German Tax Number (Steuernummer)
Germany	`eu_vat`	European VAT Number
Greece	`eu_vat`	European VAT Number
Guinea	`gn_nif`	Guinea Tax Identification Number (Número de Identificação Fiscal)
Hong Kong	`hk_br`	Hong Kong BR Number
Hungary	`eu_vat`	European VAT Number
Hungary	`hu_tin`	Hungary Tax Number (adószám)
Iceland	`is_vat`	Icelandic VAT
India	`in_gst`	Indian GST Number
Indonesia	`id_npwp`	Indonesian NPWP Number
Ireland	`eu_vat`	European VAT Number
Israel	`il_vat`	Israel VAT
Italy	`eu_vat`	European VAT Number
Japan	`jp_cn`	Japanese Corporate Number (Hōjin Bangō)
Japan	`jp_rn`	Japanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō)
Japan	`jp_trn`	Japanese Tax Registration Number (Tōroku Bangō)
Kazakhstan	`kz_bin`	Kazakhstani Business Identification Number
Kenya	`ke_pin`	Kenya Revenue Authority Personal Identification Number
Kyrgyzstan	`kg_tin`	Kyrgyzstan Tax Identification Number
Laos	`la_tin`	Laos Tax Identification Number
Latvia	`eu_vat`	European VAT Number
Liechtenstein	`li_uid`	Liechtensteinian UID Number
Liechtenstein	`li_vat`	Liechtenstein VAT Number
Lithuania	`eu_vat`	European VAT Number
Luxembourg	`eu_vat`	European VAT Number
Malaysia	`my_frp`	Malaysian FRP Number
Malaysia	`my_itn`	Malaysian ITN
Malaysia	`my_sst`	Malaysian SST Number
Malta	`eu_vat`	European VAT Number
Mauritania	`mr_nif`	Mauritania Tax Identification Number (Número de Identificação Fiscal)
Mexico	`mx_rfc`	Mexican RFC Number
Moldova	`md_vat`	Moldova VAT Number
Montenegro	`me_pib`	Montenegro PIB Number
Morocco	`ma_vat`	Morocco VAT Number
Nepal	`np_pan`	Nepal PAN Number
Netherlands	`eu_vat`	European VAT Number
New Zealand	`nz_gst`	New Zealand GST Number
Nigeria	`ng_tin`	Nigerian Tax Identification Number
North Macedonia	`mk_vat`	North Macedonia VAT Number
Northern Ireland	`eu_vat`	Northern Ireland VAT Number
Norway	`no_vat`	Norwegian VAT Number
Norway	`no_voec`	Norwegian VAT on e-commerce Number
Oman	`om_vat`	Omani VAT Number
Peru	`pe_ruc`	Peruvian RUC Number
Philippines	`ph_tin`	Philippines Tax Identification Number
Poland	`eu_vat`	European VAT Number
Portugal	`eu_vat`	European VAT Number
Romania	`eu_vat`	European VAT Number
Romania	`ro_tin`	Romanian Tax ID Number
Russia	`ru_inn`	Russian INN
Russia	`ru_kpp`	Russian KPP
Saudi Arabia	`sa_vat`	Saudi Arabia VAT
Senegal	`sn_ninea`	Senegal NINEA Number
Serbia	`rs_pib`	Serbian PIB Number
Singapore	`sg_gst`	Singaporean GST
Singapore	`sg_uen`	Singaporean UEN
Slovakia	`eu_vat`	European VAT Number
Slovenia	`eu_vat`	European VAT Number
Slovenia	`si_tin`	Slovenia Tax Number (davčna številka)
South Africa	`za_vat`	South African VAT Number
South Korea	`kr_brn`	Korean BRN
Spain	`es_cif`	Spanish NIF Number (previously Spanish CIF Number)
Spain	`eu_vat`	European VAT Number
Suriname	`sr_fin`	Suriname FIN Number
Sweden	`eu_vat`	European VAT Number
Switzerland	`ch_uid`	Switzerland UID Number
Switzerland	`ch_vat`	Switzerland VAT Number
Taiwan	`tw_vat`	Taiwanese VAT
Tajikistan	`tj_tin`	Tajikistan Tax Identification Number
Tanzania	`tz_vat`	Tanzania VAT Number
Thailand	`th_vat`	Thai VAT
Turkey	`tr_tin`	Turkish Tax Identification Number
Uganda	`ug_tin`	Uganda Tax Identification Number
Ukraine	`ua_vat`	Ukrainian VAT
United Arab Emirates	`ae_trn`	United Arab Emirates TRN
United Kingdom	`gb_vat`	United Kingdom VAT Number
United States	`us_ein`	United States EIN
Uruguay	`uy_ruc`	Uruguayan RUC Number
Uzbekistan	`uz_tin`	Uzbekistan TIN Number
Uzbekistan	`uz_vat`	Uzbekistan VAT Number
Venezuela	`ve_rif`	Venezuelan RIF Number
Vietnam	`vn_tin`	Vietnamese Tax ID Number
Zambia	`zm_tin`	Zambia Tax Identification Number
Zimbabwe	`zw_tin`	Zimbabwe Tax Identification Number

Show child attributes

created_invoices.customer_tax_id.country

enum<string>

required

Available options:

AD,

AE,

AL,

AM,

AO,

AR,

AT,

AU,

AW,

AZ,

BA,

BB,

BD,

BE,

BF,

BG,

BH,

BJ,

BO,

BR,

BS,

BY,

CA,

CD,

CH,

CL,

CM,

CN,

CO,

CR,

CV,

DE,

CY,

CZ,

DK,

DO,

EC,

EE,

EG,

ES,

ET,

EU,

FI,

FR,

GB,

GE,

GN,

GR,

HK,

HR,

HU,

ID,

IE,

IL,

IN,

IS,

IT,

JP,

KE,

KG,

KH,

KR,

KZ,

LA,

LI,

LT,

LU,

LV,

MA,

MD,

ME,

MK,

MR,

MT,

MX,

MY,

NG,

NL,

NO,

NP,

NZ,

OM,

PE,

PH,

PL,

PT,

RO,

RS,

RU,

SA,

SE,

SG,

SI,

SK,

SN,

SR,

SV,

TH,

TJ,

TR,

TW,

TZ,

UA,

UG,

US,

UY,

UZ,

VE,

VN,

ZA,

ZM,

ZW

created_invoices.customer_tax_id.type

enum<string>

required

Available options:

ad_nrt,

ae_trn,

al_tin,

am_tin,

ao_tin,

ar_cuit,

eu_vat,

au_abn,

au_arn,

aw_tin,

az_tin,

ba_tin,

bb_tin,

bd_bin,

bf_ifu,

bg_uic,

bh_vat,

bj_ifu,

bo_tin,

br_cnpj,

br_cpf,

bs_tin,

by_tin,

ca_bn,

ca_gst_hst,

ca_pst_bc,

ca_pst_mb,

ca_pst_sk,

ca_qst,

cd_nif,

ch_uid,

ch_vat,

cl_tin,

cm_niu,

cn_tin,

co_nit,

cr_tin,

cv_nif,

de_stn,

do_rcn,

ec_ruc,

eg_tin,

es_cif,

et_tin,

eu_oss_vat,

gb_vat,

ge_vat,

gn_nif,

hk_br,

hr_oib,

hu_tin,

id_npwp,

il_vat,

in_gst,

is_vat,

jp_cn,

jp_rn,

jp_trn,

ke_pin,

kg_tin,

kh_tin,

kr_brn,

kz_bin,

la_tin,

li_uid,

li_vat,

ma_vat,

md_vat,

me_pib,

mk_vat,

mr_nif,

mx_rfc,

my_frp,

my_itn,

my_sst,

ng_tin,

no_vat,

no_voec,

np_pan,

nz_gst,

om_vat,

pe_ruc,

ph_tin,

ro_tin,

rs_pib,

ru_inn,

ru_kpp,

sa_vat,

sg_gst,

sg_uen,

si_tin,

sn_ninea,

sr_fin,

sv_nit,

th_vat,

tj_tin,

tr_tin,

tw_vat,

tz_vat,

ua_vat,

ug_tin,

us_ein,

uy_ruc,

uz_tin,

uz_vat,

ve_rif,

vn_tin,

za_vat,

zm_tin,

zw_tin

created_invoices.customer_tax_id.value

string

required

created_invoices.memo

string | null

required

Free-form text which is available on the invoice PDF and the Orb invoice portal.

created_invoices.credit_notes

CreditNoteSummary · object[]

required

A list of credit notes associated with the invoice

Show child attributes

created_invoices.credit_notes.id

string

required

created_invoices.credit_notes.credit_note_number

string

required

created_invoices.credit_notes.reason

string

required

created_invoices.credit_notes.total

string

required

created_invoices.credit_notes.voided_at

string<date-time> | null

required

If the credit note has a status of void, this gives a timestamp when the credit note was voided.

Example:

"2022-05-01T07:01:31+00:00"

created_invoices.credit_notes.type

string

required

created_invoices.credit_notes.memo

string | null

required

An optional memo supplied on the credit note.

created_invoices.payment_attempts

PaymentAttempt · object[]

required

A list of payment attempts associated with the invoice

Show child attributes

created_invoices.payment_attempts.id

string

required

The ID of the payment attempt.

created_invoices.payment_attempts.payment_provider

enum<string> | null

required

The payment provider that attempted to collect the payment.

Available options:

stripe

created_invoices.payment_attempts.payment_provider_id

string | null

required

The ID of the payment attempt in the payment provider.

created_invoices.payment_attempts.amount

string

required

The amount of the payment attempt.

created_invoices.payment_attempts.succeeded

boolean

required

Whether the payment attempt succeeded.

created_invoices.payment_attempts.created_at

string<date-time>

required

The time at which the payment attempt was created.

created_invoices.payment_attempts.receipt_pdf

string | null

required

URL to the downloadable PDF version of the receipt. This field will be null for payment attempts that did not succeed.

Example:

"https://assets.withorb.com/receipt/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"

created_invoices.discount

any | null

required

deprecated

This field is deprecated in favor of discounts. If a discounts list is provided, the first discount in the list will be returned. If the list is empty, None will be returned.

created_invoices.discounts

(PercentageDiscount · object | AmountDiscount · object | TrialDiscount · object)[]

required

PercentageDiscount
AmountDiscount
TrialDiscount

Show child attributes

created_invoices.discounts.discount_type

enum<string>

required

Available options:

percentage

created_invoices.discounts.percentage_discount

number

required

Only available if discount_type is percentage. This is a number between 0 and 1.

Required range: 0 <= x <= 1

created_invoices.discounts.applies_to_price_ids

string[] | null

List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

Example:

["h74gfhdjvn7ujokd", "7hfgtgjnbvc3ujkl"]

created_invoices.discounts.filters

PriceFilter · object[] | null

The filters that determine which prices to apply this discount to.

Show child attributes

created_invoices.discounts.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

created_invoices.discounts.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

created_invoices.discounts.filters.values

string[]

required

The IDs or values that match this filter.

created_invoices.discounts.reason

string | null

created_invoices.minimum

Minimum · object

required

Show child attributes

created_invoices.minimum.minimum_amount

string

required

Minimum amount applied

created_invoices.minimum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this minimum to.

Show child attributes

created_invoices.minimum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

created_invoices.minimum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

created_invoices.minimum.filters.values

string[]

required

The IDs or values that match this filter.

created_invoices.minimum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.

created_invoices.minimum_amount

string | null

required

created_invoices.maximum

Maximum · object

required

Show child attributes

created_invoices.maximum.maximum_amount

string

required

Maximum amount applied

created_invoices.maximum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this maximum to.

Show child attributes

created_invoices.maximum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

created_invoices.maximum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

created_invoices.maximum.filters.values

string[]

required

The IDs or values that match this filter.

created_invoices.maximum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

created_invoices.maximum_amount

string | null

required

created_invoices.line_items

InvoiceLineItem · object[]

required

The breakdown of prices in this invoice.

Show child attributes

created_invoices.line_items.amount

string

required

The final amount for a line item after all adjustments and pre paid credits have been applied.

created_invoices.line_items.end_date

string<date-time>

required

The end date of the range of time applied for this line item's price.

created_invoices.line_items.grouping

string | null

required

[DEPRECATED] For configured prices that are split by a grouping key, this will be populated with the key and a value. The amount and subtotal will be the values for this particular grouping.

created_invoices.line_items.adjustments

(MonetaryUsageDiscountAdjustment · object | MonetaryAmountDiscountAdjustment · object | MonetaryPercentageDiscountAdjustment · object | MonetaryMinimumAdjustment · object | MonetaryMaximumAdjustment · object)[]

required

All adjustments applied to the line item in the order they were applied based on invoice calculations (ie. usage discounts -> amount discounts -> percentage discounts -> minimums -> maximums).

MonetaryUsageDiscountAdjustment
MonetaryAmountDiscountAdjustment
MonetaryPercentageDiscountAdjustment
MonetaryMinimumAdjustment
MonetaryMaximumAdjustment

Show child attributes

created_invoices.line_items.adjustments.id

string

required

created_invoices.line_items.adjustments.is_invoice_level

boolean

required

True for adjustments that apply to an entire invoice, false for adjustments that apply to only one price.

created_invoices.line_items.adjustments.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this adjustment to.

Show child attributes

created_invoices.line_items.adjustments.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

created_invoices.line_items.adjustments.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

created_invoices.line_items.adjustments.filters.values

string[]

required

The IDs or values that match this filter.

created_invoices.line_items.adjustments.applies_to_price_ids

string[]

required

deprecated

The price IDs that this adjustment applies to.

created_invoices.line_items.adjustments.reason

string | null

required

The reason for the adjustment.

created_invoices.line_items.adjustments.replaces_adjustment_id

string | null

required

The adjustment id this adjustment replaces. This adjustment will take the place of the replaced adjustment in plan version migrations.

created_invoices.line_items.adjustments.adjustment_type

enum<string>

required

Available options:

usage_discount

created_invoices.line_items.adjustments.usage_discount

number

required

The number of usage units by which to discount the price this adjustment applies to in a given billing period.

created_invoices.line_items.adjustments.amount

string

required

The value applied by an adjustment.

created_invoices.line_items.name

string

required

The name of the price associated with this line item.

created_invoices.line_items.quantity

number

required

Either the fixed fee quantity or the usage during the service period.

created_invoices.line_items.start_date

string<date-time>

required

The start date of the range of time applied for this line item's price.

created_invoices.line_items.subtotal

string

required

The line amount before any adjustments.

created_invoices.line_items.adjusted_subtotal

string

required

The line amount after any adjustments and before overage conversion, credits and partial invoicing.

created_invoices.line_items.credits_applied

string

required

The number of prepaid credits applied.

created_invoices.line_items.partially_invoiced_amount

string

required

Any amount applied from a partial invoice

created_invoices.line_items.sub_line_items

(MatrixSubLineItem · object | TierSubLineItem · object | OtherSubLineItem · object)[]

required

For complex pricing structures, the line item can be broken down further in sub_line_items.

MatrixSubLineItem
TierSubLineItem
OtherSubLineItem

Show child attributes

created_invoices.line_items.sub_line_items.amount

string

required

The total amount for this sub line item.

created_invoices.line_items.sub_line_items.name

string

required

created_invoices.line_items.sub_line_items.quantity

number

required

created_invoices.line_items.sub_line_items.grouping

SubLineItemGrouping · object

required

Show child attributes

created_invoices.line_items.sub_line_items.grouping.key

string

required

created_invoices.line_items.sub_line_items.grouping.value

string | null

required

No value indicates the default group

Example:

"west"

created_invoices.line_items.sub_line_items.type

enum<string>

required

Available options:

matrix

created_invoices.line_items.sub_line_items.matrix_config

SubLineItemMatrixConfig · object

required

Show child attributes

created_invoices.line_items.sub_line_items.matrix_config.dimension_values

(string | null)[]

required

The ordered dimension values for this line item.

created_invoices.line_items.sub_line_items.scaled_quantity

number | null

The scaled quantity for this line item for specific pricing structures

created_invoices.line_items.tax_amounts

TaxAmount · object[]

required

An array of tax rates and their incurred tax amounts. Empty if no tax integration is configured.

Show child attributes

created_invoices.line_items.tax_amounts.tax_rate_description

string

required

The human-readable description of the applied tax rate.

created_invoices.line_items.tax_amounts.tax_rate_percentage

string | null

required

The tax rate percentage, out of 100.

created_invoices.line_items.tax_amounts.amount

string

required

The amount of additional tax incurred by this tax rate.

created_invoices.line_items.id

string

required

A unique ID for this line item.

created_invoices.line_items.price

UnitPrice · object

required

The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill.

Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present.

For more on the types of prices, see the core concepts documentation

UnitPrice
TieredPrice
BulkPrice
BulkWithFiltersPrice
PackagePrice
MatrixPrice
ThresholdTotalAmountPrice
TieredPackagePrice
TieredWithMinimumPrice
GroupedTieredPrice
TieredPackageWithMinimumPrice
PackageWithAllocationPrice
UnitWithPercentPrice
MatrixWithAllocationPrice
TieredWithProrationPrice
UnitWithProrationPrice
GroupedAllocationPrice
BulkWithProrationPrice
GroupedWithProratedMinimumPrice
GroupedWithMeteredMinimumPrice
GroupedWithMinMaxThresholdsPrice
MatrixWithDisplayNamePrice
GroupedTieredPackagePrice
MaxGroupTieredPackagePrice
ScalableMatrixWithUnitPricingPrice
ScalableMatrixWithTieredPricingPrice
CumulativeGroupedBulkPrice
CumulativeGroupedAllocationPrice
MinimumCompositePrice
PercentCompositePrice
EventOutputPrice

Show child attributes

created_invoices.line_items.price.model_type

enum<string>

required

The pricing model type

Available options:

unit

created_invoices.line_items.price.unit_config

UnitConfig · object

required

Configuration for unit pricing

Show child attributes

created_invoices.line_items.price.unit_config.unit_amount

string

required

Rate per unit of usage

created_invoices.line_items.price.unit_config.prorated

boolean

default:false

If true, subtotals from this price are prorated based on the service period

created_invoices.line_items.price.metadata

Metadata · object

required

Show child attributes

created_invoices.line_items.price.metadata.{key}

string

created_invoices.line_items.price.id

string

required

created_invoices.line_items.price.name

string

required

created_invoices.line_items.price.external_price_id

string | null

required

created_invoices.line_items.price.replaces_price_id

string | null

required

The price id this price replaces. This price will take the place of the replaced price in plan version migrations.

created_invoices.line_items.price.price_type

enum<string>

required

Available options:

usage_price,

fixed_price,

composite_price

created_invoices.line_items.price.created_at

string<date-time>

required

created_invoices.line_items.price.cadence

enum<string>

required

Available options:

one_time,

monthly,

quarterly,

semi_annual,

annual,

custom

created_invoices.line_items.price.billing_mode

enum<string>

required

Available options:

in_advance,

in_arrear

created_invoices.line_items.price.billing_cycle_configuration

BillingCycleConfiguration · object

required

Show child attributes

created_invoices.line_items.price.billing_cycle_configuration.duration

integer

required

created_invoices.line_items.price.billing_cycle_configuration.duration_unit

enum<string>

required

Available options:

day,

month

created_invoices.line_items.price.invoicing_cycle_configuration

BillingCycleConfiguration · object

required

Show child attributes

created_invoices.line_items.price.invoicing_cycle_configuration.duration

integer

required

created_invoices.line_items.price.invoicing_cycle_configuration.duration_unit

enum<string>

required

Available options:

day,

month

created_invoices.line_items.price.billable_metric

BillableMetricTiny · object

required

Show child attributes

created_invoices.line_items.price.billable_metric.id

string

required

created_invoices.line_items.price.fixed_price_quantity

number | null

required

created_invoices.line_items.price.plan_phase_order

integer | null

required

created_invoices.line_items.price.currency

string

required

created_invoices.line_items.price.conversion_rate

number | null

required

created_invoices.line_items.price.conversion_rate_config

UnitConversionRateConfig · object

required

UnitConversionRateConfig
TieredConversionRateConfig

Show child attributes

created_invoices.line_items.price.conversion_rate_config.conversion_rate_type

enum<string>

required

Available options:

unit

created_invoices.line_items.price.conversion_rate_config.unit_config

ConversionRateUnitConfig · object

required

Show child attributes

created_invoices.line_items.price.conversion_rate_config.unit_config.unit_amount

string

required

Amount per unit of overage

created_invoices.line_items.price.item

ItemSlim · object

required

A minimal representation of an Item containing only the essential identifying information.

Show child attributes

created_invoices.line_items.price.item.id

string

required

The Orb-assigned unique identifier for the item.

created_invoices.line_items.price.item.name

string

required

The name of the item.

created_invoices.line_items.price.credit_allocation

Allocation · object

required

Show child attributes

created_invoices.line_items.price.credit_allocation.currency

string

required

created_invoices.line_items.price.credit_allocation.allows_rollover

boolean

required

created_invoices.line_items.price.credit_allocation.custom_expiration

CustomExpiration · object

required

Show child attributes

created_invoices.line_items.price.credit_allocation.custom_expiration.duration

integer

required

created_invoices.line_items.price.credit_allocation.custom_expiration.duration_unit

enum<string>

required

Available options:

day,

month

created_invoices.line_items.price.credit_allocation.filters

PriceFilter · object[]

Show child attributes

created_invoices.line_items.price.credit_allocation.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

created_invoices.line_items.price.credit_allocation.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

created_invoices.line_items.price.credit_allocation.filters.values

string[]

required

The IDs or values that match this filter.

created_invoices.line_items.price.composite_price_filters

PriceFilter · object[] | null

required

Show child attributes

created_invoices.line_items.price.composite_price_filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

created_invoices.line_items.price.composite_price_filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

created_invoices.line_items.price.composite_price_filters.values

string[]

required

The IDs or values that match this filter.

created_invoices.line_items.price.discount

PercentageDiscount · object

required

deprecated

PercentageDiscount
TrialDiscount
UsageDiscount
AmountDiscount

Show child attributes

created_invoices.line_items.price.discount.discount_type

enum<string>

required

Available options:

percentage

created_invoices.line_items.price.discount.percentage_discount

number

required

Only available if discount_type is percentage. This is a number between 0 and 1.

Required range: 0 <= x <= 1

created_invoices.line_items.price.discount.applies_to_price_ids

any

List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.

Example:

["h74gfhdjvn7ujokd", "7hfgtgjnbvc3ujkl"]

created_invoices.line_items.price.discount.filters

any

The filters that determine which prices to apply this discount to.

created_invoices.line_items.price.discount.reason

any

created_invoices.line_items.price.minimum

Minimum · object

required

deprecated

Show child attributes

created_invoices.line_items.price.minimum.minimum_amount

string

required

Minimum amount applied

created_invoices.line_items.price.minimum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this minimum to.

Show child attributes

created_invoices.line_items.price.minimum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

created_invoices.line_items.price.minimum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

created_invoices.line_items.price.minimum.filters.values

string[]

required

The IDs or values that match this filter.

created_invoices.line_items.price.minimum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this minimum amount applies to. For plan/plan phase minimums, this can be a subset of prices.

created_invoices.line_items.price.minimum_amount

string | null

required

deprecated

created_invoices.line_items.price.maximum

Maximum · object

required

deprecated

Show child attributes

created_invoices.line_items.price.maximum.maximum_amount

string

required

Maximum amount applied

created_invoices.line_items.price.maximum.filters

PriceFilter · object[]

required

The filters that determine which prices to apply this maximum to.

Show child attributes

created_invoices.line_items.price.maximum.filters.field

enum<string>

required

The property of the price to filter on.

Available options:

price_id,

item_id,

price_type,

currency,

pricing_unit_id

created_invoices.line_items.price.maximum.filters.operator

enum<string>

required

Should prices that match the filter be included or excluded.

Available options:

includes,

excludes

created_invoices.line_items.price.maximum.filters.values

string[]

required

The IDs or values that match this filter.

created_invoices.line_items.price.maximum.applies_to_price_ids

string[]

required

deprecated

List of price_ids that this maximum amount applies to. For plan/plan phase maximums, this can be a subset of prices.

created_invoices.line_items.price.maximum_amount

string | null

required

deprecated

created_invoices.line_items.price.dimensional_price_configuration

DimensionalPriceConfiguration · object

Show child attributes

created_invoices.line_items.price.dimensional_price_configuration.dimensional_price_group_id

string

required

created_invoices.line_items.price.dimensional_price_configuration.dimension_values

string[]

required

created_invoices.line_items.usage_customer_ids

string[] | null

required

A list of customer ids that were used to calculate the usage for this line item.

created_invoices.line_items.filter

string | null

required

An additional filter that was used to calculate the usage for this line item.

created_invoices.subtotal

string

required

The total before any discounts and minimums are applied.

created_invoices.invoice_date

string<date-time>

required

The scheduled date of the invoice

Fetch customer credits ledger by external ID List top-ups by external ID

⌘I

API documentation

Alert

Coupon

Credit

Credit note

Customer

Dimensional Price Group

Event

Invoice

Item

Metric

Availability

Plan

Price

Subscription Change

Subscription

Price interval

Create ledger entry by external ID

Effects of adding a ledger entry

Adding credits

Invoicing for credits

Deducting Credits

Changing credits expiry

Voiding credits

Amendment

Authorizations

Path Parameters

Body

Response

Supported Tax ID Countries and Types