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 '{
  "metadata": {},
  "currency": "<string>",
  "description": "<string>",
  "entry_type": "increment",
  "amount": 123,
  "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"
  }
}'

{
  "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>"
  },
  "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": "8.00",
      "created_at": "2022-05-01T07:01:31+00:00",
      "currency": "USD",
      "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": "JYEFHK-00001",
      "subscription": {
        "id": "VDGsT23osdLb84KD"
      },
      "total": "8.00",
      "customer_balance_transactions": [
        {
          "id": "cgZa3SXcsPTVyC4Y",
          "created_at": "2022-05-01T07:01:31+00:00",
          "starting_balance": "33.00",
          "ending_balance": "22.00",
          "amount": "11.00",
          "action": "applied_to_invoice",
          "description": "An optional description",
          "invoice": {
            "id": "gXcsPTVyC4YZa3Sc"
          },
          "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": "<any>",
      "discounts": [
        {
          "discount_type": "percentage",
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            "<any>"
          ],
          "reason": "<string>",
          "percentage_discount": 0.15
        }
      ],
      "minimum": {
        "minimum_amount": "<string>",
        "filters": [
          "<any>"
        ],
        "applies_to_price_ids": [
          "<any>"
        ]
      },
      "minimum_amount": "<string>",
      "maximum": {
        "maximum_amount": "<string>",
        "filters": [
          "<any>"
        ],
        "applies_to_price_ids": [
          "<any>"
        ]
      },
      "maximum_amount": "<string>",
      "line_items": [
        {
          "amount": "7.00",
          "discount": {
            "discount_type": "percentage",
            "applies_to_price_ids": [
              "h74gfhdjvn7ujokd",
              "7hfgtgjnbvc3ujkl"
            ],
            "filters": [
              "<any>"
            ],
            "reason": "<string>",
            "percentage_discount": 0.15
          },
          "end_date": "2022-02-01T08:00:00+00:00",
          "grouping": "<string>",
          "minimum": {
            "minimum_amount": "<string>",
            "filters": [
              "<any>"
            ],
            "applies_to_price_ids": [
              "<any>"
            ]
          },
          "minimum_amount": "<string>",
          "maximum": {
            "maximum_amount": "<string>",
            "filters": [
              "<any>"
            ],
            "applies_to_price_ids": [
              "<any>"
            ]
          },
          "maximum_amount": "<string>",
          "adjustments": [
            {
              "id": "<string>",
              "is_invoice_level": true,
              "filters": [
                {}
              ],
              "applies_to_price_ids": [
                "<string>"
              ],
              "reason": "<string>",
              "replaces_adjustment_id": "<string>",
              "adjustment_type": "usage_discount",
              "usage_discount": 123,
              "amount": "<string>"
            }
          ],
          "name": "Fixed Fee",
          "quantity": 1,
          "start_date": "2022-02-01T08:00:00+00:00",
          "subtotal": "9.00",
          "adjusted_subtotal": "5.00",
          "credits_applied": "6.00",
          "partially_invoiced_amount": "4.00",
          "sub_line_items": [
            {
              "amount": "9.00",
              "name": "Tier One",
              "quantity": 5,
              "grouping": {},
              "type": "matrix",
              "matrix_config": {
                "dimension_values": [
                  "<any>"
                ]
              }
            }
          ],
          "tax_amounts": [
            {
              "tax_rate_description": "<string>",
              "tax_rate_percentage": "<string>",
              "amount": "<string>"
            }
          ],
          "id": "<string>",
          "price": {
            "model_type": "unit",
            "unit_config": {
              "unit_amount": "<string>",
              "scaling_factor": 123
            },
            "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_cycle_configuration": {
              "duration": "<any>",
              "duration_unit": "<any>"
            },
            "invoicing_cycle_configuration": {
              "duration": "<any>",
              "duration_unit": "<any>"
            },
            "billable_metric": {
              "id": "<string>"
            },
            "dimensional_price_configuration": {
              "dimensional_price_group_id": "<string>",
              "dimension_values": [
                "<any>"
              ]
            },
            "fixed_price_quantity": 123,
            "plan_phase_order": 123,
            "currency": "<string>",
            "conversion_rate": 123,
            "conversion_rate_config": {},
            "item": {
              "id": "<string>",
              "name": "<string>"
            },
            "credit_allocation": {
              "currency": "<string>",
              "allows_rollover": true,
              "custom_expiration": "<any>"
            },
            "composite_price_filters": [
              {}
            ],
            "discount": {},
            "minimum": {
              "minimum_amount": "<any>",
              "filters": "<any>",
              "applies_to_price_ids": "<any>"
            },
            "minimum_amount": "<string>",
            "maximum": {
              "maximum_amount": "<any>",
              "filters": "<any>",
              "applies_to_price_ids": "<any>"
            },
            "maximum_amount": "<string>"
          },
          "usage_customer_ids": [
            "<string>"
          ],
          "filter": "<string>"
        }
      ],
      "subtotal": "8.00",
      "invoice_date": "2022-05-01T07:00:00+00:00"
    }
  ]
}

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 '{
  "metadata": {},
  "currency": "<string>",
  "description": "<string>",
  "entry_type": "increment",
  "amount": 123,
  "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"
  }
}'

{
  "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>"
  },
  "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": "8.00",
      "created_at": "2022-05-01T07:01:31+00:00",
      "currency": "USD",
      "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": "JYEFHK-00001",
      "subscription": {
        "id": "VDGsT23osdLb84KD"
      },
      "total": "8.00",
      "customer_balance_transactions": [
        {
          "id": "cgZa3SXcsPTVyC4Y",
          "created_at": "2022-05-01T07:01:31+00:00",
          "starting_balance": "33.00",
          "ending_balance": "22.00",
          "amount": "11.00",
          "action": "applied_to_invoice",
          "description": "An optional description",
          "invoice": {
            "id": "gXcsPTVyC4YZa3Sc"
          },
          "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": "<any>",
      "discounts": [
        {
          "discount_type": "percentage",
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            "<any>"
          ],
          "reason": "<string>",
          "percentage_discount": 0.15
        }
      ],
      "minimum": {
        "minimum_amount": "<string>",
        "filters": [
          "<any>"
        ],
        "applies_to_price_ids": [
          "<any>"
        ]
      },
      "minimum_amount": "<string>",
      "maximum": {
        "maximum_amount": "<string>",
        "filters": [
          "<any>"
        ],
        "applies_to_price_ids": [
          "<any>"
        ]
      },
      "maximum_amount": "<string>",
      "line_items": [
        {
          "amount": "7.00",
          "discount": {
            "discount_type": "percentage",
            "applies_to_price_ids": [
              "h74gfhdjvn7ujokd",
              "7hfgtgjnbvc3ujkl"
            ],
            "filters": [
              "<any>"
            ],
            "reason": "<string>",
            "percentage_discount": 0.15
          },
          "end_date": "2022-02-01T08:00:00+00:00",
          "grouping": "<string>",
          "minimum": {
            "minimum_amount": "<string>",
            "filters": [
              "<any>"
            ],
            "applies_to_price_ids": [
              "<any>"
            ]
          },
          "minimum_amount": "<string>",
          "maximum": {
            "maximum_amount": "<string>",
            "filters": [
              "<any>"
            ],
            "applies_to_price_ids": [
              "<any>"
            ]
          },
          "maximum_amount": "<string>",
          "adjustments": [
            {
              "id": "<string>",
              "is_invoice_level": true,
              "filters": [
                {}
              ],
              "applies_to_price_ids": [
                "<string>"
              ],
              "reason": "<string>",
              "replaces_adjustment_id": "<string>",
              "adjustment_type": "usage_discount",
              "usage_discount": 123,
              "amount": "<string>"
            }
          ],
          "name": "Fixed Fee",
          "quantity": 1,
          "start_date": "2022-02-01T08:00:00+00:00",
          "subtotal": "9.00",
          "adjusted_subtotal": "5.00",
          "credits_applied": "6.00",
          "partially_invoiced_amount": "4.00",
          "sub_line_items": [
            {
              "amount": "9.00",
              "name": "Tier One",
              "quantity": 5,
              "grouping": {},
              "type": "matrix",
              "matrix_config": {
                "dimension_values": [
                  "<any>"
                ]
              }
            }
          ],
          "tax_amounts": [
            {
              "tax_rate_description": "<string>",
              "tax_rate_percentage": "<string>",
              "amount": "<string>"
            }
          ],
          "id": "<string>",
          "price": {
            "model_type": "unit",
            "unit_config": {
              "unit_amount": "<string>",
              "scaling_factor": 123
            },
            "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_cycle_configuration": {
              "duration": "<any>",
              "duration_unit": "<any>"
            },
            "invoicing_cycle_configuration": {
              "duration": "<any>",
              "duration_unit": "<any>"
            },
            "billable_metric": {
              "id": "<string>"
            },
            "dimensional_price_configuration": {
              "dimensional_price_group_id": "<string>",
              "dimension_values": [
                "<any>"
              ]
            },
            "fixed_price_quantity": 123,
            "plan_phase_order": 123,
            "currency": "<string>",
            "conversion_rate": 123,
            "conversion_rate_config": {},
            "item": {
              "id": "<string>",
              "name": "<string>"
            },
            "credit_allocation": {
              "currency": "<string>",
              "allows_rollover": true,
              "custom_expiration": "<any>"
            },
            "composite_price_filters": [
              {}
            ],
            "discount": {},
            "minimum": {
              "minimum_amount": "<any>",
              "filters": "<any>",
              "applies_to_price_ids": "<any>"
            },
            "minimum_amount": "<string>",
            "maximum": {
              "maximum_amount": "<any>",
              "filters": "<any>",
              "applies_to_price_ids": "<any>"
            },
            "maximum_amount": "<string>"
          },
          "usage_customer_ids": [
            "<string>"
          ],
          "filter": "<string>"
        }
      ],
      "subtotal": "8.00",
      "invoice_date": "2022-05-01T07:00:00+00:00"
    }
  ]
}

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

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

object | null

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

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

object | null

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

Response

Created

The Credit Ledger Entry resource models prepaid credits within Orb.

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

string

required

ledger_sequence_number

integer

required

entry_status

enum<string>

required

Available options:

committed,

pending

customer

object

required

Show child attributes

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

object

required

Show child attributes

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

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

API documentation

Alert

Coupon

Credit note

Customer

Credit

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